feat: add some new workflow apis #125
Conversation
|
|
WalkthroughIntroduces workflow listing and retrieval capabilities: new Retrofit WorkflowAPI, request/response DTOs and models, WorkflowService methods (list/get) with wiring updates in CozeAPI, accompanying unit tests, and a Maven version bump from 0.4.2 to 0.4.3. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant WorkflowService
participant WorkflowAPI as Retrofit WorkflowAPI
participant Server as HTTP Server
rect rgba(220,235,255,0.5)
note over Client,Server: List workflows
Client->>WorkflowService: list(WorkflowListReq)
WorkflowService->>WorkflowAPI: list(workspace_id, page_num, ...)
WorkflowAPI->>Server: GET /v1/workflows?...
Server-->>WorkflowAPI: 200 BaseResponse<WorkflowListResp>
WorkflowAPI-->>WorkflowService: Call.execute() result
WorkflowService-->>Client: BaseResponse<WorkflowListResp>
end
rect rgba(235,255,220,0.5)
note over Client,Server: Get workflow
Client->>WorkflowService: get(WorkflowGetReq)
WorkflowService->>WorkflowAPI: get(workflow_id, include_input_output)
WorkflowAPI->>Server: GET /v1/workflows/{workflow_id}?include_input_output=...
Server-->>WorkflowAPI: 200 BaseResponse<WorkflowGetResp>
WorkflowAPI-->>WorkflowService: Call.execute() result
WorkflowService-->>Client: BaseResponse<WorkflowGetResp>
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Pre-merge checks (2 passed, 1 warning)❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Poem
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Flag potential breaking changes that are not documented:
1. Identify changes to public APIs/exports, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints (including removed/renamed items and changes to types, required params, return values, defaults, or behavior).
2. Ignore purely internal/private changes (e.g., code not exported from package entry points or marked internal).
3. Verify documentation exists: a "Breaking Change" section in the PR description and updates to CHANGELOG.md.Please share your feedback with us on this Discord post. ✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@chyroc 帮忙合并下分支 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (20)
api/pom.xml (1)
181-185: Upgrade test logging dependency.
logback-classic 1.2.x is quite old; consider 1.4.x/1.5.x to avoid known issues and align with modern SLF4J.- <version>1.2.3</version> + <version>1.4.14</version>api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowCreator.java (1)
10-22: Harden JSON model against unknown fields.
Add @JsonIgnoreProperties(ignoreUnknown = true) for forward-compatibility with API additions.+import com.fasterxml.jackson.annotation.JsonIgnoreProperties; ... -@Data +@Data +@JsonIgnoreProperties(ignoreUnknown = true) public class WorkflowCreator {api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (1)
12-21: Ignore unknown JSON for input schema.
Safeguards deserialization when the server adds fields.+import com.fasterxml.jackson.annotation.JsonIgnoreProperties; ... -@Data +@Data +@JsonIgnoreProperties(ignoreUnknown = true) public class WorkflowInput {api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java (1)
14-19: Add unknown-field tolerance.
Consistent with other DTOs, ignore unknown JSON fields.+import com.fasterxml.jackson.annotation.JsonIgnoreProperties; ... -@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonIgnoreProperties(ignoreUnknown = true) public class WorkflowListResp {api/src/main/java/com/coze/openapi/api/WorkflowAPI.java (1)
16-24: Optional: reduce parameter churn with @QueryMap.
Consider switching list(...) to accept a Map (or req -> Map) to avoid frequent signature changes as filters evolve.- Call<BaseResponse<WorkflowListResp>> list( - @Query("workspace_id") String workspaceId, - @Query("page_num") Integer pageNum, - @Query("page_size") Integer pageSize, - @Query("workflow_mode") String workflowMode, - @Query("app_id") String appId, - @Query("publish_status") String publishStatus, - @Tag BaseReq baseReq); + Call<BaseResponse<WorkflowListResp>> list( + @QueryMap Map<String, Object> query, + @Tag BaseReq baseReq);api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
14-30: Ignore unknown fields on get response.
Prevents breakage if the API adds properties.+import com.fasterxml.jackson.annotation.JsonIgnoreProperties; ... -@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonIgnoreProperties(ignoreUnknown = true) public class WorkflowGetResp {api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (1)
12-26: Tighten typing and null-handling.
- Add @JsonInclude(NON_NULL).
- Consider an enum for terminatePlan to avoid magic strings.
+import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; ... -@Data -@Builder -@NoArgsConstructor -@AllArgsConstructor +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonIgnoreProperties(ignoreUnknown = true) public class WorkflowOutput { @@ - @JsonProperty("terminate_plan") - private String terminatePlan; + @JsonProperty("terminate_plan") + private String terminatePlan; // consider enumOptionally, introduce:
public enum TerminatePlan { return_variables, use_answer_content }api/src/test/java/com/coze/openapi/service/service/workflow/WorkFlowServiceTest.java (3)
36-36: Rename test class to match service naming.Use WorkflowServiceTest (no internal capital F) for consistency with WorkflowService and typical Java style.
85-96: Capture and assert forwarded query params to WorkflowAPI.list.Strengthen the test by verifying the exact arguments passed to Retrofit, ensuring mapping from WorkflowListReq is correct.
Add imports:
import static org.mockito.ArgumentMatchers.eq; import static org.mockito.ArgumentMatchers.isNull; import static org.mockito.Mockito.verify;Apply inside testList after assertions:
assertEquals(workflowID, result.getData().getItems().get(0).getWorkflowId()); + verify(workflowAPI) + .list(eq(workSpaceId), eq(pageNum), isNull(), isNull(), isNull(), isNull(), any());
98-163: Add negative-path tests (HTTP error/non-0 code/null body).Cover failure cases for list/get to assert Utils.execute error wrapping and surface stability.
api/src/main/java/com/coze/openapi/service/service/workflow/WorkflowService.java (1)
37-51: Fail fast on required fields; guard against nulls.Validate required request fields before delegating, to avoid surprising 4xxs from server and easier debugging.
+import java.util.Objects; ... public BaseResponse<WorkflowListResp> list(WorkflowListReq req) { - return Utils.execute( + Objects.requireNonNull(req, "req must not be null"); + Objects.requireNonNull(req.getWorkspaceId(), "workspaceId must not be null"); + Objects.requireNonNull(req.getPageNum(), "pageNum must not be null"); + return Utils.execute( workflowAPI.list( req.getWorkspaceId(), req.getPageNum(), req.getPageSize(), req.getWorkflowMode(), req.getAppId(), req.getPublishStatus(), req)); } ... public BaseResponse<WorkflowGetResp> get(WorkflowGetReq req) { - return Utils.execute(workflowAPI.get(req.getWorkflowId(), req.getIncludeInputOutput(), req)); + Objects.requireNonNull(req, "req must not be null"); + Objects.requireNonNull(req.getWorkflowId(), "workflowId must not be null"); + return Utils.execute(workflowAPI.get(req.getWorkflowId(), req.getIncludeInputOutput(), req)); }api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetReq.java (3)
6-12: Enable builder default for includeInputOutput.Remove @nonnull and default to false so callers aren’t forced to set it explicitly.
import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Builder; import lombok.AllArgsConstructor; import lombok.Data; import lombok.EqualsAndHashCode; import lombok.NoArgsConstructor; -import lombok.NonNull; import lombok.experimental.SuperBuilder;
25-29: Default includeInputOutput to false (and optional).Matches doc’s default and keeps query param omitted unless set.
- /** 是否在返回结果中返回输入和输出参数的结构体。 true：返回输入输出参数结构体 false：不返回输入输出参数结构体 默认值为 false。 */ - @NonNull - @JsonProperty("include_input_output") - private Boolean includeInputOutput; + /** 是否在返回结果中返回输入和输出参数的结构体。默认 false。 */ + @Builder.Default + @JsonProperty("include_input_output") + private Boolean includeInputOutput = Boolean.FALSE;
20-24: Consider validating workflowId non-empty.If bean validation is available, add @notblank; otherwise, service-level null/empty checks suffice.
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
16-19: Use camelCase field name for appId.Aligns with Java conventions while keeping JSON mapping unchanged.
/** 工作流关联的应用 ID。若工作流未关联任何应用，则该字段值为 0 */ @JsonProperty("app_id") - private String app_id; + private String appId;api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java (2)
27-29: Fix comment for properties.The text mentions “数组元素的子类型” for object; should describe object properties.
- /** 当参数类型为 object 时，该字段用于定义数组元素的子类型。 */ + /** 当参数类型为 object 时，该字段用于定义对象的子属性。 */
33-35: Use Object for defaultValue to preserve numeric/boolean defaults.String forces lossy coercion for non-string defaults.
- /** 该参数配置的默认值。 */ - @JsonProperty("default_value") - private String defaultValue; + /** 该参数配置的默认值（类型与参数类型匹配）。 */ + @JsonProperty("default_value") + private Object defaultValue;api/src/main/java/com/coze/openapi/client/workflows/WorkflowListReq.java (3)
6-12: Enable builder defaults support.Required for using @Builder.Default fields below.
import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Builder; import lombok.AllArgsConstructor; import lombok.Data; import lombok.EqualsAndHashCode; import lombok.NoArgsConstructor; import lombok.NonNull; import lombok.experimental.SuperBuilder;
29-31: Default pageSize to 10 per docs.Avoid forcing callers to set it; server default is 10.
/** 查询结果分页展示时，此参数用于设置每页返回的数据量。取值范围为 1 ~ 30，默认为 10。 */ - @JsonProperty("page_size") - private Integer pageSize; + @Builder.Default + @JsonProperty("page_size") + private Integer pageSize = 10;
33-43: Consider enums and basic validation for filters.workflowMode and publishStatus as enums (WORKFLOW/CHATFLOW, ALL/PUBLISHED_ONLINE/UNPUBLISHED_DRAFT) and add simple bounds checks (@Min/@max) for pageNum/pageSize if bean validation is available.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
api/pom.xml(1 hunks)api/src/main/java/com/coze/openapi/api/WorkflowAPI.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetReq.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/WorkflowListReq.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowCreator.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java(1 hunks)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java(1 hunks)api/src/main/java/com/coze/openapi/service/service/CozeAPI.java(1 hunks)api/src/main/java/com/coze/openapi/service/service/workflow/WorkflowService.java(2 hunks)api/src/test/java/com/coze/openapi/service/service/workflow/WorkFlowServiceTest.java(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (9)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowListReq.java (3)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetReq.java (1)
Data(13-29)api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java (1)
Data(14-26)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
Data(10-40)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java (2)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowListReq.java (1)
Data(13-44)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
Data(10-40)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowCreator.java (1)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
Data(10-40)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java (3)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
Data(14-30)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (1)
Data(12-21)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (1)
Data(12-27)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (3)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
Data(10-40)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (1)
Data(12-21)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (1)
Data(12-27)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetReq.java (5)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
Data(14-30)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
Data(10-40)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (1)
Data(12-21)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (1)
Data(12-27)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java (1)
Data(12-36)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (3)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
Data(14-30)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (1)
Data(12-27)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java (1)
Data(12-36)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (3)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
Data(14-30)api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java (1)
Data(14-26)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowCreator.java (1)
Data(10-22)
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowOutput.java (3)
api/src/main/java/com/coze/openapi/client/workflows/WorkflowGetResp.java (1)
Data(14-30)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowInput.java (1)
Data(12-21)api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowParameter.java (1)
Data(12-36)
🔇 Additional comments (9)
api/pom.xml (2)
46-46: Version bump to 0.4.3 looks good.
Matches the added public API surface.
245-249: Confirm lombok.version is defined upstream.
This POM references ${lombok.version} but doesn’t define it locally. Ensure the parent POM provides it; otherwise the build will fail.If missing, add in :
+ <lombok.version>1.18.32</lombok.version>api/src/main/java/com/coze/openapi/service/service/CozeAPI.java (1)
218-223: WorkflowService constructor signature aligns with all call sites and tests.api/src/main/java/com/coze/openapi/api/WorkflowAPI.java (1)
16-31: API mappings look correct.
Paths, query names, and @tag usage align with the docs summary.api/src/test/java/com/coze/openapi/service/service/workflow/WorkFlowServiceTest.java (2)
31-31: Potential Utils package mismatch with production code.Tests import com.coze.openapi.utils.Utils, while WorkflowService imports com.coze.openapi.service.utils.Utils. Verify only one Utils exists and align both to the same package to avoid confusion/duplicate helpers.
70-71: Timestamp format in test conflicts with model comments.You set ISO-8601 strings for createdAt/updatedAt, but model comments say “Unix timestamp seconds”. Confirm the API format and make tests/models consistent.
api/src/main/java/com/coze/openapi/service/service/workflow/WorkflowService.java (2)
12-12: Verify correct Utils import.Service uses com.coze.openapi.service.utils.Utils, tests use com.coze.openapi.utils.Utils. Unify to one package to prevent divergence.
39-46: Double-check Retrofit method signature and param order.Ensure WorkflowAPI.list(...) parameter order matches these calls; otherwise queries will be misrouted.
api/src/main/java/com/coze/openapi/client/workflows/model/WorkflowDetail.java (1)
26-30: Confirm createdAt/updatedAt types vs API.Comments say Unix seconds, fields are String, and tests use ISO-8601. Validate the actual wire format from docs and adjust types/comments accordingly (e.g., Long seconds or ISO-8601 String).
| /** 标识当前返回的工作流列表是否还有更多数据未返回。 true ：还有更多未返回的回调应用。 false：已返回所有数据。 */ | ||
| @JsonProperty("has_more") | ||
| private Boolean hasMore; |
There was a problem hiding this comment.
Fix Javadoc: “回调应用” → “工作流”.
Current description is misleading in generated docs.
- /** 标识当前返回的工作流列表是否还有更多数据未返回。 true ：还有更多未返回的回调应用。 false：已返回所有数据。 */
+ /** 标识当前返回的工作流列表是否还有更多数据未返回。 true：还有更多未返回的工作流。 false：已返回所有数据。 */📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| /** 标识当前返回的工作流列表是否还有更多数据未返回。 true ：还有更多未返回的回调应用。 false：已返回所有数据。 */ | |
| @JsonProperty("has_more") | |
| private Boolean hasMore; | |
| /** 标识当前返回的工作流列表是否还有更多数据未返回。 true：还有更多未返回的工作流。 false：已返回所有数据。 */ | |
| @JsonProperty("has_more") | |
| private Boolean hasMore; |
🤖 Prompt for AI Agents
In api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java
around lines 23 to 25, the Javadoc for hasMore mistakenly uses “回调应用”; update
the comment to replace “回调应用” with “工作流” so the description reads that true
means there are more workflows not returned and false means all workflows have
been returned; keep the existing @JsonProperty and field unchanged.
There was a problem hiding this comment.
🧩 Analysis chain
@tcsp 经过查证，我理解您的观点。如果这个描述确实来自于官方文档，那么保持与官方文档一致是合理的做法。我的建议可能过于武断了。
不过，如果您有时间的话，建议您可以向官方反馈这个术语的一致性问题 - 在工作流相关的API文档中使用"回调应用"这个术语可能会让开发者产生困惑，因为我们讨论的是工作流（workflows），而不是回调应用（callback applications）。
但您说得对，如果这是官方文档的原文，那么现在保持一致是正确的选择。
🏁 Script executed:
#!/bin/bash
# Look for any mentions of "回调应用" in the codebase to understand the context
rg "回调应用" --type java -C 3
Length of output: 725
@tcsp 您说得对，保持与官方文档的一致性确实更重要。通过搜索确认这是代码库中唯一出现"回调应用"的地方，既然这是官方文档的原文，那么保持原样是正确的做法。
感谢您的澄清！
✏️ Learnings added
Learnt from: tcsp
PR: coze-dev/coze-java#125
File: api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java:23-25
Timestamp: 2025-09-09T11:11:47.738Z
Learning: 在API文档的中文注释中，"回调应用"这个术语可能出现在官方文档中，即使在工作流相关的API中使用也应该保持与官方文档的一致性。
Learnt from: tcsp
PR: coze-dev/coze-java#125
File: api/src/main/java/com/coze/openapi/client/workflows/WorkflowListResp.java:23-25
Timestamp: 2025-09-09T11:11:47.738Z
Learning: 当API文档的注释来自官方文档时，应该保持与官方文档的完全一致，即使术语可能在特定上下文中显得不够精确，也不应该擅自修改。保持与官方文档的一致性比术语的完美性更重要。
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
doc reference：
https://www.coze.cn/open/docs/developer_guides/get_workflow_list
https://www.coze.cn/open/docs/developer_guides/get_workflow_info