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.
2 participants
doc reference：
https://www.coze.cn/open/docs/developer_guides/get_workflow_list
https://www.coze.cn/open/docs/developer_guides/get_workflow_info