@leiax00/yushe-agent-kit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/.agents/dsh/plugins/yushe-user-rules/README.md +66 -0
  2. package/.agents/dsh/plugins/yushe-user-rules/cordis.patch.yml +5 -0
  3. package/.agents/dsh/plugins/yushe-user-rules/index.js +561 -0
  4. package/.agents/dsh/plugins/yushe-user-rules/package.json +9 -0
  5. package/.agents/rules/docs-management.md +16 -0
  6. package/.agents/rules/git-workflow.md +74 -0
  7. package/.agents/rules/interaction.md +35 -0
  8. package/.agents/skills/yx-api-design/SKILL.md +15 -0
  9. package/.agents/skills/yx-api-design/references/evolution.md +11 -0
  10. package/.agents/skills/yx-api-design/references/http-contract.md +33 -0
  11. package/.agents/skills/yx-api-design/references/idempotency.md +13 -0
  12. package/.agents/skills/yx-backend-architecture/SKILL.md +77 -0
  13. package/.agents/skills/yx-backend-architecture/references/common/clean-design.md +51 -0
  14. package/.agents/skills/yx-backend-architecture/references/common/common.md +31 -0
  15. package/.agents/skills/yx-backend-architecture/references/go/guide.md +9 -0
  16. package/.agents/skills/yx-backend-architecture/references/java/api-layout.md +103 -0
  17. package/.agents/skills/yx-backend-architecture/references/java/coding-style.md +36 -0
  18. package/.agents/skills/yx-backend-architecture/references/java/data-objects.md +68 -0
  19. package/.agents/skills/yx-backend-architecture/references/java/enums-and-constants.md +42 -0
  20. package/.agents/skills/yx-backend-architecture/references/java/framework-boundaries.md +25 -0
  21. package/.agents/skills/yx-backend-architecture/references/java/input-contracts.md +39 -0
  22. package/.agents/skills/yx-backend-architecture/references/java/integrations.md +54 -0
  23. package/.agents/skills/yx-backend-architecture/references/java/logging-and-audit.md +29 -0
  24. package/.agents/skills/yx-backend-architecture/references/java/mybatis-plus.md +65 -0
  25. package/.agents/skills/yx-backend-architecture/references/java/record-vs-class.md +74 -0
  26. package/.agents/skills/yx-backend-architecture/references/java/repositories-and-modules.md +95 -0
  27. package/.agents/skills/yx-backend-architecture/references/java/spring-boot.md +35 -0
  28. package/.agents/skills/yx-backend-architecture/references/java/structure.md +69 -0
  29. package/.agents/skills/yx-backend-architecture/references/java/verification.md +36 -0
  30. package/.agents/skills/yx-backend-architecture/references/python/guide.md +9 -0
  31. package/.agents/skills/yx-backend-architecture/references/typescript/guide.md +9 -0
  32. package/.agents/skills/yx-database-design/SKILL.md +16 -0
  33. package/.agents/skills/yx-database-design/references/engines.md +17 -0
  34. package/.agents/skills/yx-database-design/references/index-and-transactions.md +11 -0
  35. package/.agents/skills/yx-database-design/references/migrations.md +13 -0
  36. package/.agents/skills/yx-database-design/references/modeling.md +13 -0
  37. package/.agents/skills/yx-docs/SKILL.md +32 -0
  38. package/.agents/skills/yx-docs/references/layout.md +102 -0
  39. package/.agents/skills/yx-docs/references/module-docs.md +60 -0
  40. package/.agents/skills/yx-docs/references/notes.md +39 -0
  41. package/.agents/skills/yx-docs/references/reading-protocol.md +25 -0
  42. package/.agents/skills/yx-docs/references/releases.md +63 -0
  43. package/.agents/skills/yx-docs/references/when-to-write.md +33 -0
  44. package/.agents/skills/yx-docs/references/writing-guide.md +80 -0
  45. package/.agents/skills/yx-frontend-architecture/SKILL.md +16 -0
  46. package/.agents/skills/yx-frontend-architecture/references/frameworks.md +15 -0
  47. package/.agents/skills/yx-frontend-architecture/references/state-and-interaction.md +11 -0
  48. package/.agents/skills/yx-frontend-architecture/references/structure.md +11 -0
  49. package/LICENSE +21 -0
  50. package/README.md +76 -2
  51. package/dist/bin/yak.js +11 -0
  52. package/dist/cli/fsx.js +72 -0
  53. package/dist/cli/kit.js +47 -0
  54. package/dist/cli/main.js +132 -0
  55. package/dist/cli/targets/claude.js +47 -0
  56. package/dist/cli/targets/dsh.js +61 -0
  57. package/dist/cli/targets/registry.js +33 -0
  58. package/dist/cli/targets/types.js +1 -0
  59. package/package.json +40 -4
@@ -0,0 +1,74 @@
1
+ ---
2
+ alwaysApply: true
3
+ ---
4
+
5
+ # 分支与提交规范(团队共识)
6
+
7
+ 项目已有分支约定时以项目约定为准。
8
+
9
+ ## 分支管理
10
+
11
+ 采用简化 trunk-based(SHOULD):
12
+
13
+ 1. `main` 始终保持可用:合入前 MUST 确认构建/测试通过(或说明无法验证的原因)。
14
+ 2. 功能开发从 `main` 拉分支,命名 `feat/<简短主题>`;修复用 `fix/<问题>`;实验性探索用 `try/<主题>`(可不合入)。
15
+ 3. 分支生命周期尽量短(SHOULD,一两天内量级);长期分支定期同步 `main`。
16
+ 4. 直接在 `main` 上提交仅限微小改动(typo、文档修正);其余情况 SHOULD 走分支。
17
+ 5. 分支合并后删除;不合入的探索分支注明原因后删除。
18
+
19
+ ## 提交信息格式
20
+
21
+ ```text
22
+ <type>(<scope>): <中文描述>
23
+
24
+ <可选正文>
25
+ ```
26
+
27
+ ### Type
28
+
29
+ - `feat`:新增能力
30
+ - `fix`:修复问题
31
+ - `refactor`:重构
32
+ - `docs`:文档
33
+ - `test`:测试
34
+ - `chore`:工程维护
35
+ - `perf`:性能
36
+ - `ci`:持续集成
37
+
38
+ `scope` 标识改动所属模块,可用时 SHOULD 提供(如 `docs(aes): …`)。
39
+
40
+ ### 提交正文
41
+
42
+ 1. 提交正文应尽量紧凑:
43
+ - 只有一个整体说明时,使用一个自然段。
44
+ - 有多个独立改动点时,在同一个正文中使用无序列表;列表项之间不要插入空行。
45
+ - 不要把每个小点都拆成独立段落;多个 `-m` 参数只用于确实需要分隔的正文段落。
46
+
47
+ 2. 推荐使用多个 `-m` 参数表达标题和正文:
48
+
49
+ ```bash
50
+ git commit -m "docs(aes): 新增编排与状态设计文档" \
51
+ -m $'- 拆分编排引擎、DSL 与 GraphArtifact 设计\n- 补充状态分层与恢复机制说明'
52
+ ```
53
+
54
+ 如果正文是一段完整摘要,也可以直接写成:
55
+
56
+ ```bash
57
+ git commit -m "fix(aes): 修正 thread 恢复判断" \
58
+ -m "修正重连后未按原 graph_artifact_key 恢复兼容版本的问题。"
59
+ ```
60
+
61
+ 不要在普通双引号中写 `\n` 期待它变成换行;普通双引号会把它作为字面量传给 Git。不添加 AI attribution 署名。
62
+
63
+ ### 提交粒度
64
+
65
+ 一次提交一个主题(MUST NOT 混合无关改动);同一任务的关联变更一起提交,保持每个提交可独立回退。不提交与摘要无关的文件(如本地调试产物、IDE 配置)。
66
+
67
+ ## 安全边界
68
+
69
+ - 不自动执行 `git commit`;建议提交时询问用户,选项显式区分「仅提交」与「提交并推送」,不得只有合并选项。
70
+ - **提交与推送是两个独立授权阶段:用户批准提交不代表批准推送**。`git push`(含 tag 推送)必须用户单独显式授权;严禁在用户仅答复提交时链式执行 push。
71
+ - 询问未获答复(被关闭/跳过)时视为未授权:不提交也不推送,以文本再次确认。
72
+ - 不自动执行合并分支、打 tag,除非用户明确要求。
73
+ - 不使用 `git push --force` 覆盖共享分支。
74
+ - 提交前检查敏感文件、`git diff --check` 和与改动范围匹配的验证命令;MUST NOT 带着已知失败提交并谎称通过。
@@ -0,0 +1,35 @@
1
+ ---
2
+ alwaysApply: true
3
+ ---
4
+
5
+ # 交互原则(vibe coding 基础约定)
6
+
7
+ 团队共识(SHOULD 级默认,偏离时说明理由),适用于每个新会话、上下文压缩后、或用户要求继续之前工作的场景。
8
+
9
+ ## 语言规则(强制)
10
+
11
+ - 所有与用户的自然语言交流 MUST 使用简体中文,包括讨论、分析、解释、设计、建议、总结等;不允许自动切换为英文。
12
+ - 文档输出 MUST 使用简体中文。
13
+ - 例外:代码本身不受语言限制;代码的注释说明使用中文;标准技术名词可保留英文;第三方库名称保持原样。
14
+
15
+ ## 会话启动
16
+
17
+ 1. **先恢复上下文再动手**:读取任务相关文件、最近的提交和未完成事项,重建对项目现状的认识;不凭印象假设代码或配置长什么样。
18
+ 2. **对齐理解**:会话开始时用一两句话复述对当前任务的理解和计划;理解模糊或需求矛盾时先问,不做大改动赌方向。
19
+ 3. **尊重既有约定**:项目已有规范(AGENTS.md、既有代码风格、目录结构)优先于个人偏好;发现规则冲突时指出,不静默按自己的判断改。
20
+
21
+ ## 推进方式
22
+
23
+ 4. **小步快跑**:一次聚焦一个主题,改动保持可验证、可回退;大任务先拆步骤,每步完成后简报结果。
24
+ 5. **改动最小化**:只改与任务直接相关的文件;不顺手重构、不升级依赖、不清理无关告警,除非用户要求。
25
+ 6. **破坏性操作先确认**:删除文件、覆盖内容、强推、操作共享环境前,说明影响并等待明确同意。
26
+
27
+ ## 汇报诚实
28
+
29
+ 7. **区分事实与推断**:说"我读了 X"仅当真的读过;推断的内容标注为推断,不冒充验证结果。
30
+ 8. **如实报告失败**:命令失败、测试不过、未能完成的步骤如实说明,不隐瞒、不粉饰、不把计划表述为已完成。
31
+ 9. **标注未验证项**:交付时明确哪些经过验证、哪些没有;静态检查通过不等于运行验证通过。
32
+
33
+ ## 用户偏好
34
+
35
+ 10. 用户的显式要求 > 本文件任何规则;规则与用户要求冲突时按用户要求执行,涉及风险时提示一句即可,不反复纠缠。
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: yx-api-design
3
+ description: 设计或评审 HTTP API 契约、资源命名、分页、错误、幂等、兼容性及前后端协作;用于新增接口或变更公共契约,不规定内部服务和数据库分层。
4
+ ---
5
+
6
+ # API 设计
7
+
8
+ 先阅读现有 OpenAPI/接口文档、客户端、网关及认证约定,确定消费者和兼容要求。已有接口风格优先,不为统一外观破坏已发布契约。
9
+
10
+ 1. 路径、字段、分页、状态码与错误读取 [HTTP 契约](references/http-contract.md)。
11
+ 2. 写操作重试、并发修改和跨服务调用读取 [幂等与并发](references/idempotency.md)。
12
+ 3. 新版本、字段演进及契约验证读取 [兼容与验证](references/evolution.md)。
13
+ 4. 后端实现、前端交互和数据库设计分别按需要显式加载对应 Skill;本 Skill 是契约职责边界,不是自动依赖管理器。
14
+
15
+ 输出可实现的契约:方法/路径、认证与授权、参数、请求/响应示例、失败语义、分页/幂等规则和兼容影响。项目已有 OpenAPI 时更新其源文件,不同时维护相互矛盾的多套定义。验证必须覆盖实际请求与响应,不能只检查文档能解析。
@@ -0,0 +1,11 @@
1
+ # 契约演进与验证
2
+
3
+ 识别消费者:浏览器、移动端、第三方和内部服务的升级速度不同。新增必填请求字段、字段类型变化、错误码变化、分页变化和删除枚举值通常需要兼容策略。新增响应字段或枚举值也可能破坏严格客户端,应检查其解析行为。
4
+
5
+ 优先保持向后兼容的增量变更;有意破坏兼容时定义版本、迁移窗口、弃用说明及旧版本观测。不要机械为每个接口添加 v1,也不要默认“内部接口可以随时改”。
6
+
7
+ OpenAPI 或项目已有 schema 应描述认证、字段约束、可空性、响应类型和错误。以选定规范版本表示 null,不混用不同 OpenAPI 版本语法。契约生成代码仍需要实现与业务验证。
8
+
9
+ 验证覆盖:合法样例、缺失/非法字段、越权访问、分页边界、排序稳定、重复幂等键、并发版本冲突和实际错误结构。兼容变更用旧客户端/契约检查验证。示例只使用虚构数据;不存在的测试环境明确标为未验证。
10
+
11
+ 跨 Skill 任务先确定契约,再分别落实前端、后端和迁移;如果实现约束迫使契约改变,回到本契约显式调整,避免各层各自发明字段或错误码。
@@ -0,0 +1,33 @@
1
+ # HTTP 契约规范
2
+
3
+ ## 资源与方法
4
+
5
+ 沿用项目资源命名和版本策略。GET 用于读取且不触发业务写操作;POST 创建或执行业务命令;PUT 与 PATCH 的替换/部分修改语义需明确。复杂业务动作可显式建模如取消订单,不必为了 CRUD 风格暴露任意状态修改。
6
+
7
+ 使用合适 HTTP 状态:成功创建可返回 201 和资源位置,异步受理用 202 并提供状态查询语义;无响应体的 204 不再附 JSON。认证失败、无权访问、不存在、状态冲突与参数错误分别表达,沿用项目的 400/422 策略。不能把所有错误都包装为 HTTP 200。
8
+
9
+ ## 字段与输入
10
+
11
+ 区分字段省略、null、空字符串、空数组。标明必填、长度、数值范围、格式和未知字段处理。金额、大整数、日期/时间精度与时区在客户端之间一致,必要时用字符串表达精确值。请求 DTO 使用字段白名单,禁止绑定内部 entity。
12
+
13
+ 身份与 tenant 不直接信任客户端字段。查询、下载、批量接口也需资源级授权。对允许的筛选和排序字段建立白名单,限制 pageSize、批量数量和请求体大小。
14
+
15
+ ## 列表
16
+
17
+ 数据量较小且需要跳页时可用页码分页;明确从 0 还是 1 开始、页大小上限以及 total 是否存在/精确。大数据或持续变化列表评估游标分页,定义稳定排序和唯一 tie-breaker;游标应绑定筛选/排序和访问范围,不能作为授权凭证。
18
+
19
+ ## 错误
20
+
21
+ 使用稳定机器可读错误码、人类可读说明及请求追踪标识;字段错误可带字段路径。错误文案不是客户端分支条件。可沿用已有错误封装或 Problem Details 风格,但不为采用新格式强改已发布接口。不要返回堆栈、SQL、密钥或可用于枚举敏感资源的信息。
22
+
23
+ 示例(字段名按项目契约调整):
24
+
25
+ ```json
26
+ {"code":"ORDER_STATE_CONFLICT","message":"订单当前状态不允许取消","requestId":"req-example"}
27
+ ```
28
+
29
+ 服务端权限校验为权威依据;是否对不存在和无权限统一返回 404 由资源泄露策略决定。
30
+
31
+ ## Java 模块 API 与 HTTP API
32
+
33
+ Java 的 api 包是同 JVM 公开模块契约,HTTP Controller 位于模块 internal/web;跨服务通信仍以 HTTP/RPC/消息协议为边界。外部状态码默认使用显式稳定字符串业务码,不暴露 Java ordinal/name;定义未知枚举值处理策略。具体 Java Port/Adapter 与 DTO 归属由 yx-backend-architecture 负责。
@@ -0,0 +1,13 @@
1
+ # 幂等、并发与重试
2
+
3
+ 先描述重复执行的业务后果。HTTP 方法的幂等语义不代表响应必须相同;POST 如创建订单、支付应按需求定义幂等协议,而非只建议前端禁用按钮。
4
+
5
+ 幂等键至少绑定调用方/租户、操作和请求摘要。相同键相同内容返回原结果或明确处理中状态;相同键不同内容返回冲突。定义有效期、可重试失败、处理中超时恢复和结果保存范围。
6
+
7
+ 服务端用唯一约束、原子占位等机制处理并发,不能只“先查缓存再写”。业务写入与幂等记录需有明确一致性边界;如果跨外部服务,定义外部幂等键和恢复对账。缓存过期后是否允许再次执行需在契约中说明。
8
+
9
+ 并发编辑使用版本字段或 ETag/If-Match 等项目已有协议,冲突时提示重新读取;避免无条件覆盖。区分业务状态冲突与暂时性故障,客户端不能对所有 4xx 自动重试。
10
+
11
+ 对限流、暂时不可用和超时定义退避及重试预算。超时意味着结果未知,不等于操作未执行。写入重试应使用同一幂等键,并能查询最终结果。
12
+
13
+ 事件交付应定义事件 ID、版本、排序需求与重复处理语义,不承诺仅靠网络传输实现 exactly-once。
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: yx-backend-architecture
3
+ description: 设计、实现或评审后端模块、服务编排与持久化边界;提供 Java/Spring Boot/MyBatis-Plus 架构和编码规范,以及 TypeScript、Python、Go 的基础指南。
4
+ ---
5
+
6
+ # 后端架构
7
+
8
+ ## 适用范围
9
+
10
+ 用于后端架构、业务实现、重构和代码评审。Java 规范覆盖较完整;其他语言目前是基础指南,不能宣称具有同等覆盖或验证程度。
11
+
12
+ ## 工作方式与规则优先级
13
+
14
+ 1. 读取适用项目规则、目标代码、依赖与相关测试,确认已有改动和任务范围。
15
+ 2. 明确任务语言与实际变化,仅加载下面命中的参考文档;纯局部修改不要求重新选择全项目架构。
16
+ 3. 实现最小完整变化,执行与风险匹配的检查;不自动升级依赖、扩大重构或操作共享环境。
17
+
18
+ 用户明确要求与适用项目规则优先。MUST/MUST NOT 表示必须/禁止;SHOULD 是默认建议,偏离说明原因;MAY 可选。既有契约兼容与新规则冲突时说明具体位置和迁移影响,不静默改变行为。
19
+
20
+ 参考链接用于条件导航,不意味着递归加载全部引用。已读且未改变的内容无需反复读取;任务扩大或发现新风险时再补读。
21
+
22
+ ## Java
23
+
24
+ ### 最小必读
25
+
26
+ 新增、修改或评审 Java 代码,读取 [编码基线](references/java/coding-style.md)。不因修改很小忽略明确的编码要求,也不为遵守架构模板扩写无关代码。
27
+
28
+ ### 按任务加载
29
+
30
+ 每行只负责一个主题;多主题任务取并集,不默认全部加载。
31
+
32
+ | 任务或变化 | 参考 |
33
+ |---|---|
34
+ | 新建模块、调整包或架构边界 | [Java 结构](references/java/structure.md) |
35
+ | 应用编排、数据访问边界、多仓储、能力分包 | [Repository 与模块](references/java/repositories-and-modules.md) |
36
+ | 对象归属、跨层复用、构造器、Builder、Lombok | [数据对象与构建](references/java/data-objects.md) |
37
+ | 新增类型、修改可变性/相等性、record/class 转换 | [类型选择](references/java/record-vs-class.md) |
38
+ | Java 模块公开接口、DTO 或 api 子包 | [api 组织](references/java/api-layout.md) |
39
+ | 跨模块/跨服务调用、入站/出站、事件 | [集成边界](references/java/integrations.md) |
40
+ | 枚举、常量、配置、业务错误码 | [所有权与编码](references/java/enums-and-constants.md) |
41
+ | Spring 事务、异常映射、客户端装配 | [Spring Boot](references/java/spring-boot.md) |
42
+ | SQL、MyBatis-Plus、填充、锁与分页 | [持久化规范](references/java/mybatis-plus.md) |
43
+ | 外部请求绑定、PATCH、缺失/null/默认值语义、可信范围(不是所有 DTO 修改) | [输入契约](references/java/input-contracts.md) |
44
+ | 日志或审计 | [日志与审计](references/java/logging-and-audit.md) |
45
+ | 提炼公共技术模块或 starter | [框架边界](references/java/framework-boundaries.md) |
46
+ | 拆方法/类、引入模式、可读性重构 | [简洁设计](references/common/clean-design.md)(跨语言) |
47
+ | 选择测试、架构评审、较复杂行为变更 | [验证指南](references/java/verification.md) |
48
+
49
+ DTO 按实际变化选文档:内部 DTO 的归属或构建看数据对象;新增类型再看类型选择;只有外部输入绑定/语义变化才读输入契约。仅沿用既有类型增改字段,不默认三份全读。Java 具体规则已在专题展开,不默认补读通用原则。
50
+
51
+ ### 验证与交付
52
+
53
+ 运行项目已有的适用检查;小改动检查相关行为,大改动按验证指南选择证据。说明实际执行结果、兼容影响和未验证项,不把规范加载或编译通过视作真实数据库/HTTP 验收。
54
+
55
+ ## TypeScript
56
+
57
+ 成熟度:基础指南。读取 [TypeScript 入口](references/typescript/guide.md);涉及架构边界时补读 [通用原则](references/common/common.md),涉及可读性重构、命名或设计模式选择时补读 [简洁设计](references/common/clean-design.md)。按项目实际框架扩展,不能套用 Java 的 Repository 或类继承模板。
58
+
59
+ ## Python
60
+
61
+ 成熟度:基础指南。读取 [Python 入口](references/python/guide.md);涉及架构边界时补读 [通用原则](references/common/common.md),涉及可读性重构、命名或设计模式选择时补读 [简洁设计](references/common/clean-design.md)。同步/异步与数据库生命周期按现有技术栈核实。
62
+
63
+ ## Go
64
+
65
+ 成熟度:基础指南。读取 [Go 入口](references/go/guide.md);涉及架构边界时补读 [通用原则](references/common/common.md),涉及可读性重构、命名或设计模式选择时补读 [简洁设计](references/common/clean-design.md)。使用 Go 包、消费方接口与显式错误语义,不照搬 Java 分层。
66
+
67
+ ## 跨领域协作
68
+
69
+ - 改变外部接口契约:显式加载 `yx-api-design`。
70
+ - 改变数据模型、索引或迁移:显式加载 `yx-database-design`。
71
+ - 前端页面/组件开发:交由 `yx-frontend-architecture`。
72
+
73
+ 这些是按任务调用的独立 Skill,不自动依赖或继承。不可用时说明缺失并依据已有项目契约工作。
74
+
75
+ ## 输出要求
76
+
77
+ 简述改动、实质取舍和验证结果。评审给出位置、触发条件与影响。仅用户需要完整方案时输出架构文档,不为每次小改动生成流程报告。
@@ -0,0 +1,51 @@
1
+ # 可读性与简洁设计(所有语言)
2
+
3
+ ## 目标与原则
4
+
5
+ 最终代码应让维护者从名称、模块和用例流程读懂业务,保持简单、高内聚、低耦合。以 KISS(保持简单)、YAGNI(没有当前需求就不实现)和《代码整洁之道》的可读性理念作为设计方向;不把个人阈值伪装成书籍逐字规定。
6
+
7
+ MUST 实现当前已明确的需求和必要正确性,不为猜测中的扩展生成空接口、通用框架、可插拔工厂、抽象基类或备用分支。KISS/YAGNI 不意味着省略认证、输入验证、事务/并发处理和必要失败语义。
8
+
9
+ 本文件是跨语言原则;排版、命名和参数数量等编码细则由各语言指南(如 Java 编码基线)定义,持久化与架构边界由对应专题文档负责。
10
+
11
+ ## 命名与函数
12
+
13
+ - 名称表达业务意图和单位,避免 data、info、process、handle 等无上下文万能名字;少量上下文明确的 Handler 命名按现有用例规则保持一致。
14
+ - 一个方法处理一个清楚的任务,尽量保持同一抽象层次:顶层读起来是业务步骤,底层负责具体转换/IO。
15
+ - 用 guard clause 减少嵌套,分支结构遵循语言与团队编码基线;避免嵌套三元、过长布尔表达式和难追踪的超长链式调用。具名条件只有能解释业务含义时才抽取。
16
+ - 纯查询不隐藏写入或远程副作用;方法名与返回值体现操作语义。异常和失败信息有业务含义,不吞异常后返回虚假成功。
17
+ - 不用固定行数逼出大量跳转方法;拆分后应减少理解成本,而不是把连续简单逻辑切碎。
18
+ - 注释解释业务原因、边界、不可见约束和取舍,避免复述每行代码;公共契约说明语义、参数约束、失败和副作用。不要用长注释弥补模糊命名,修改行为时同步注释。
19
+
20
+ ## 内聚、耦合与 DRY
21
+
22
+ 类/模块中的状态与行为应围绕同一业务职责,避免巨型服务、万能 Utils 和字段大杂烩。依赖只暴露调用方需要的能力,传递必要数据,不传整个请求上下文、容器或无关聚合。
23
+
24
+ 业务模型优先组合,继承需有合理替换语义;框架提供的技术基类复用仅限技术实现边界,不推广到业务继承。SOLID 用来判断职责和变化边界,不要求每个类都有接口或每个分支都有策略。
25
+
26
+ DRY 优先消除重复业务知识;两段外观相似但变化原因不同的逻辑可保留独立。看到第二处重复时先辨认语义,不急于把所有类似字段和步骤合并为复杂泛型工具。
27
+
28
+ ## 按问题选模式,不按模式造问题
29
+
30
+ | 模式/手段 | 合适信号 | 不应采用的情况 |
31
+ |---|---|---|
32
+ | Strategy | 已存在多种可替换业务算法且需要独立演进 | 只有一个实现,或几个清楚稳定的简单分支 |
33
+ | Factory | 创建规则、类型选择或不变量需要集中保护 | 只给一次构造套同名静态方法 |
34
+ | Builder | 多字段有同一语义且无法合理拆分,需要命名构建 | 简单两字段值对象也生成一整套构建体系 |
35
+ | Adapter / Port | 隔离外部系统、存储和模块契约差异 | 每层机械增加一个只转发的接口 |
36
+ | State | 复杂状态转换规则分散且需要集中维护 | 少量状态用清楚的枚举行为即可表达 |
37
+ | Chain of Responsibility | 多个独立步骤确有顺序/组合变化需求 | 固定三个校验也建立可编排流水线引擎 |
38
+ | Observer / 事件 | 已发生事实需要多个独立消费者 | 立即要结果的普通调用被改成异步 |
39
+
40
+ 采用模式前明确当前问题、最简单方案为何不足、增加哪些类型与复杂度,以及如何验证收益。无需另写设计文档;在任务说明中用一句话说明有实质取舍的决定即可。模式名称不是质量指标。
41
+
42
+ ## 完成前自审
43
+
44
+ 1. 新维护者能否从用例入口顺序读懂业务?名称是否需要额外解释?
45
+ 2. 哪个类/方法承担了两个变化原因?拆分是否真的减少理解成本?
46
+ 3. 是否存在仅为未来准备的接口、选项、工厂、通用父类或未使用代码?删除无当前用途内容。
47
+ 4. 构建与依赖是否满足对应语言的编码基线,而非用参数袋或伪抽象绕过约束?
48
+ 5. 重构有没有改变返回值、异常、事务边界或副作用顺序?用针对行为的测试证明。
49
+ 6. 代码是否符合对应语言编码规范,同时保留原有模块边界?
50
+
51
+ 对纯排版不补镜像测试;对行为变更覆盖关键成功、失败和边界用例。优先让实现与测试都能解释业务,避免测试内部方法次数来锁死合理重构。
@@ -0,0 +1,31 @@
1
+ # 通用后端架构原则
2
+
3
+ ## 模块和依赖
4
+
5
+ 优先按业务能力划分模块,如订单、库存、支付;模块内部再按职责分层。以一条业务用例确认依赖方向,避免只按 controller/service/mapper 建立全项目大目录。
6
+
7
+ 简单 CRUD 使用接口层→应用服务→持久化适配器即可。只有复杂业务规则、状态机或多个基础设施实现需要隔离时,引入 domain 和 ports。不要为每张表机械创建聚合,也不要强制拆成微服务或多个构建模块。
8
+
9
+ 领域模型不依赖 Web、数据库或远程 SDK。应用层编排用例、权限上下文和事务;基础设施实现持久化与外部服务端口。跨边界查询模型遵循所属语言的公开契约与数据所有权规则。
10
+
11
+ ## 对象和共享代码
12
+
13
+ 请求/响应 DTO 表示外部契约,领域对象维护业务不变量,持久化对象表达存储结构。简单模块可减少内部转换;不可因此把数据库实体作为公共请求绑定对象。DTO 的复用以契约相同且生命周期相同为条件,不因字段相似而共用。
14
+
15
+ 共享模块只容纳稳定、无业务方向依赖的基础能力。避免 common/utils 逐渐成为互相依赖的业务中心。跨服务共享契约应独立版本化,不能共享 ORM 实体替代接口。
16
+
17
+ ## 一致性和失败
18
+
19
+ 用数据库约束兜底唯一性,用条件更新、版本号或锁明确并发策略。先检查再写入无法单独防止竞态。
20
+
21
+ 本地事务只保护同一事务资源内的操作。数据库事务无法回滚已发出的 HTTP 请求。需要可靠事件交付时评估事务 outbox、重试和消费者去重;不要把“提交后发送一次”描述成可靠投递。
22
+
23
+ 远程调用定义超时、失败语义和重试预算。仅对可安全重试的操作重试,避免多层重试放大流量;有副作用的调用需幂等协议。缓存说明数据来源、失效策略和可接受陈旧时间,不承担最终唯一性约束。
24
+
25
+ ## 复杂度与验证
26
+
27
+ 从一个实际用例和一个失败用例开始,确认权限校验、业务校验、持久化和返回值的归属。日志记录关联标识和可操作信息,不输出凭据或完整敏感对象。验证优先覆盖业务不变量、权限、边界、事务和并发,避免只测试框架委托方法。
28
+
29
+ ## 模块公开面与内部实现
30
+
31
+ 对采用模块化架构的新模块,区分稳定公开契约与内部实现;各语言用合适的导出机制保护边界,具体命名由语言指南规定。跨模块只通过公开面交互,应用用例按功能聚合,不建立全局万能 DTO/常量目录。
@@ -0,0 +1,9 @@
1
+ # Go 后端扩展入口
2
+
3
+ 检查 go.mod、工具链、路由和数据库驱动。包以业务能力命名,利用 internal 控制可见性;避免为模仿 Java 建立大量空层和接口。
4
+
5
+ 接口优先由消费方按最小需要定义,具体类型实现细节留在适配器。显式传播 context、截止时间和取消;不要把请求 context 长期保存到结构体。事务使用实际驱动的 Tx 并明确 commit/rollback,不能跨 goroutine 假定事务安全。
6
+
7
+ 错误携带上下文并通过 errors.Is/As 等项目约定识别;HTTP 边界映射稳定错误。并发任务明确退出与资源释放,避免无界 goroutine。sqlc、GORM 或 database/sql 均按已有选型封装,不强制替换。
8
+
9
+ 新增框架或数据层规则放在本目录,更新 SKILL.md 的条件路由;优先补充实际使用的 sqlc/GORM 或路由框架指南。
@@ -0,0 +1,103 @@
1
+ # Java 模块 api 包组织
2
+
3
+ ## 公开什么,再决定怎么分包
4
+
5
+ api 是业务模块面向同 JVM 消费方的稳定 Java 契约,不是 HTTP Controller 目录,也不是所有 DTO/枚举的收纳处。先确认实际消费者和公开能力,再创建所需子包;没有跨模块调用时不生成空 api 门面。
6
+
7
+ MUST 只公开消费者确实需要的接口和数据。契约中的参数、返回值、泛型元素、公开异常和它们递归引用的自定义类型也必须可合法访问;不能用 public DTO 包装内部类型来间接泄露 internal。
8
+
9
+ ## 跨模块访问边界(统一定义)
10
+
11
+ 跨业务模块只依赖提供方 api;不得访问其内部 Repository、Mapper、DO、Service 或直接写其表。参数、结果和递归引用的自定义类型都必须满足公开契约要求。internal 中的 public 类型不会自动不可见,需要架构检查或依赖审查。
12
+
13
+ 经明确允许的专用跨表只读模型属于查询例外,不因此放开内部类型依赖或跨模块写入。具体同 JVM/远程调用及 Adapter 选择,涉及调用时读取 [集成边界](integrations.md)。
14
+
15
+ ## 小模块可以平铺
16
+
17
+ 只有一个查询接口、少量紧密相关的数据类型时,以下结构足够:
18
+
19
+ ```text
20
+ device/
21
+ ├── api/
22
+ │ ├── DeviceQueryApi.java
23
+ │ └── DeviceSnapshot.java
24
+ └── internal/
25
+ ├── web/
26
+ ├── application/
27
+ ├── domain/
28
+ └── infrastructure/
29
+ ```
30
+
31
+ 不为了只有一个 DTO 强行建 dto/result/response 三层包,也不预先创建 command、event、error 空目录。
32
+
33
+ ## 默认扩展结构:按契约职责拆分
34
+
35
+ 公开类型增加、平铺已不便理解时,SHOULD 采用以下结构,只创建实际用到的部分:
36
+
37
+ ```text
38
+ device/api/
39
+ ├── DeviceQueryApi.java # 对外查询能力
40
+ ├── DeviceCommandApi.java # 对外写能力,有需要才存在
41
+ ├── dto/
42
+ │ ├── DeviceSnapshot.java # 返回快照
43
+ │ ├── DeviceSummary.java # 摘要
44
+ │ ├── DevicePageQuery.java # 公开查询条件
45
+ │ └── RegisterDeviceCommand.java # 公开写入输入
46
+ ├── type/
47
+ │ ├── DeviceStatus.java # 公开状态枚举
48
+ │ └── DeviceKind.java # 公开分类枚举
49
+ ├── event/
50
+ │ └── DeviceRegisteredEvent.java # 供其他模块消费的事实
51
+ └── error/
52
+ └── DeviceErrorCode.java # 消费方需要识别的错误契约
53
+ ```
54
+
55
+ 接口直接放 api 根包,不再无意义地加 service/interface/facade。按消费者需要划分查询与写接口,不强制读写分离,也不建暴露全部 CRUD 的万能 DeviceApi。
56
+
57
+ 示例选用 `type`,因为此分类允许同时包含公开枚举与稳定标识/值类型;这是组织偏好,不具有技术优越性。若只收纳枚举,`enums` 同样清晰合理;优先沿用项目命名,不同时维护两个同义包,也不把 `type` 当作杂物包。
58
+
59
+ 公开 DTO 放模块自己的 api/dto;不存在全项目 common/dto。DTO 用业务名称或 Command/Query/Snapshot 等角色名,不因放在 dto 包就统一追加 DTO 后缀。
60
+
61
+ ## dto 是否继续细分
62
+
63
+ 只有公开输入/输出类型已形成明显集合且查找困难时,MAY 将 dto 细分为 command、query、result;平铺示例中的快照和摘要可归 result。不要同时设置 result、response、vo 三套同义分类。
64
+
65
+ 此处 Req/Resp 若专属于 HTTP,仍放 internal/web;Java 模块调用的 Command/Query 不应为了外观一致改成 HTTP Req。同名业务用例的内部 Command 默认仍放 internal/application;当它本身就是稳定公开契约时可由 api 拥有并被 application 直接消费,前提是不依赖 internal。真正语义不同或需独立演进时才映射为内部对象。
66
+
67
+ ## 更大模块:按公开能力聚合
68
+
69
+ 当多个公开能力拥有相互独立的消费者和变化原因,可以改为按能力组织:
70
+
71
+ ```text
72
+ device/api/
73
+ ├── registration/
74
+ │ ├── DeviceRegistrationApi.java
75
+ │ ├── RegisterDeviceCommand.java
76
+ │ └── DeviceRegistrationResult.java
77
+ ├── inventory/
78
+ │ ├── DeviceInventoryApi.java
79
+ │ ├── DeviceInventoryQuery.java
80
+ │ └── DeviceInventoryItem.java
81
+ ├── type/ # 仅真正跨上述能力共用的契约类型
82
+ └── event/
83
+ ```
84
+
85
+ 不同时保留 api/dto/registration 与 api/registration/dto 两套位置。模块仍小时优先平铺或默认职责结构;能力划分持续膨胀时检查业务模块边界,不只增加目录深度。没有固定类数阈值,依据理解成本和独立变化决定。
86
+
87
+ ## 枚举、事件和错误的所有权
88
+
89
+ - `api/type/DeviceStatus` 表达消费者看到的业务状态;内部生命周期状态和规则归 internal/domain。两者语义相同时可以共享稳定公开类型,语义不同时映射,不能为了避免一个转换公开内部状态机。
90
+ - 公开类型本身不依赖持久化注解、Web 或内部业务实现。独立部署的服务仍按字符串 code/协议处理枚举与未知值,不能因为存在 Java api/type 就要求服务共享内部枚举 Jar。
91
+ - api/event 只放明确供其他模块消费的事实快照。内部领域事件留在 internal,外部 MQ schema 在 messaging 适配;MQ Topic、序列化实现和 Producer/Consumer 不放 api。
92
+ - api/error 只公开调用方需要识别和处理的错误码/错误类型。内部异常和诊断细节不全部暴露,HTTP 状态映射仍由 web 负责。
93
+ - 技术常量、缓存 key、重试参数、Mapper、DO、RepositoryImpl、Feign/HTTP 客户端都不得放 api。
94
+
95
+ ## 实现、数据类型与边界验证
96
+
97
+ 公开接口如何由应用服务实现、是否需要适配层,统一见 [集成边界](integrations.md),仅在实现或调整调用链时补读。
98
+
99
+ 公开 DTO/快照按 [record/class 选择](record-vs-class.md) 默认评估 record;枚举仍为 enum,公开能力为 interface,实现为 class。排版与参数数量建议遵循已读编码基线;改变构建方式时按主入口加载数据对象文档。
100
+
101
+ 按 api/internal 划包不是自动可见性控制。使用架构工具时检查实际配置是否覆盖 api 子包、跨包引用和允许依赖,不能假定导出 api 根包就必然递归导出所有子包;具体语法按项目使用的工具版本核实。没有自动检查时明确进行依赖审查。
102
+
103
+ 移动公开 Java 类型到子包会改变全限定名,可能破坏源码、二进制或反射配置。旧契约按兼容要求渐进迁移,不将目录整理当成无行为风险的格式修改。只维护 Skill 时不声称业务仓库已完成这些迁移。
@@ -0,0 +1,36 @@
1
+ # Java 最小编码基线
2
+
3
+ 每次 Java 变更必读。本文件是排版、参数数量建议和规范优先级的权威定义;对象构建与架构细则按任务读取,不在此展开。
4
+
5
+ ## 强制格式
6
+
7
+ - 方法、构造器、compact constructor 无论多短都展开;左花括号在声明末尾,语句另起行,结束右花括号独占一行。空实现也分行;无实现的接口/抽象方法使用分号。
8
+ - if/else、for/增强 for、while/do 语句体必须有花括号。else if 可连续表达,各分支体仍展开。
9
+ - 一行一条语句、一个字段声明;4 空格缩进,不用 Tab。record 的每个组件独占一行,头部左括号后换行,右括号另起一行。
10
+ - 多步 Builder 链每次调用一行。单表达式 Lambda 可简写,语句块多行;不通过 Lambda 或嵌套三元压缩复杂控制流。
11
+
12
+ ## 参数数量:团队强烈建议
13
+
14
+ SHOULD 将自有方法、接口方法和手写构造器控制在 3 个显式参数以内。这是团队共识的强烈建议,为可读性设定,不是普适硬上限或阿里巴巴手册原文。
15
+
16
+ 超过 3 个时优先检查职责,将共同表达一个请求、查询条件或业务概念的参数封装为有明确名称的对象。不要机械凑成三字段分组,也不要用 Map/Object[]/任意 varargs/万能 Context 隐藏参数。
17
+
18
+ 若参数没有自然聚合语义,封装反而降低可读性,或受既有/外部签名约束,可保留超过 3 个参数并简述理由,无需单独申请批准。构造注入以职责内聚为先:依赖多时检查服务职责,不把服务依赖装进参数对象,也不用字段注入、服务定位器或 Lombok 隐藏依赖。
19
+
20
+ record 隐式 canonical constructor 和 Builder 生成构造器不按手写参数个数机械评判;调用处仍应避免难读的长串位置参数。多字段构建按需读取 [构建规则](data-objects.md)。
21
+
22
+ ## 可读性与范围
23
+
24
+ 遵循 KISS/YAGNI:实现当前需求与必要正确性,不生成猜测性接口、模式、空目录和备用功能。名称体现业务意图;不因排版或减少参数牺牲授权、事务和失败语义。结构重构或模式选择时再读 [简洁设计](../common/clean-design.md)。
25
+
26
+ ## 外部规范与团队覆盖项
27
+
28
+ 以 [阿里巴巴 P3C](https://github.com/alibaba/p3c) 的适用编码规则为参考基线,尚未锁定一个完整手册版本/检查配置,不能宣称全面符合某一版阿里巴巴手册。依赖外部条款做决定时,核对项目采用版本及规则,不仅凭 Skill 概述。
29
+
30
+ 项目格式要求:多行方法体、record 逐字段换行;团队强烈建议:参数不超过 3 个;新代码 Req/Resp、XxxAppService、业务名领域类型;接口与 Repository 按当前架构设计,不照搬历史手册所有 Service/DAO 接口或 Enum 后缀约定。格式/参数规则源自用户要求,不冒充外部原文。
31
+
32
+ 涉及对象构建、DTO 归属或命名时读取 [数据对象](data-objects.md);涉及架构时读取主入口对应文档。其他适用阿里巴巴规则没有因此被整体豁免,具体冲突需说明。
33
+
34
+ ## 执行检查
35
+
36
+ 运行现有 formatter/静态检查及相关行为测试,审阅未覆盖部分;未配置 CI 时如实说明。不要自动安装整套工具,不用简单正则替代 Java 语法检查。本 Skill 是工作指导,不等于自动强制或验证通过。
@@ -0,0 +1,68 @@
1
+ # 数据对象、值对象与跨层传输
2
+
3
+ MUST 按语义和契约所有权划分对象,不按“每经过一层复制一次”划分。
4
+
5
+ | 角色 | 默认命名 | 归属 |
6
+ |---|---|---|
7
+ | HTTP 输入/输出 | CreateDeviceReq、DeviceResp | internal/web;需要时按项目约定细分请求/响应包 |
8
+ | 写用例输入 | CreateDeviceCommand | internal/application;复杂用例按需放 create |
9
+ | 查询输入/结果 | DevicePageQuery、DeviceListItem、DeviceDetail | internal/application;复杂查询按需放 list |
10
+ | 领域实体/聚合 | Device、UpgradeRule | internal/domain,规模增加再细分 model |
11
+ | 领域值对象 | Imei、VersionNumber、Money | 领域概念附近 |
12
+ | 持久化对象 | DeviceDO | internal/infrastructure/persistence |
13
+ | 模块公开契约 | DeviceSnapshot | api,由提供方管理 |
14
+ | 远程传输对象 | RemoteDeviceResp | 消费方 infrastructure/integration |
15
+
16
+ 新代码 SHOULD 使用 DO 表示数据库映射,不用 Entity 指代数据库表对象;领域实体使用业务名称。HTTP 响应用 Resp,不用含义模糊的 VO;领域 Value Object 用业务名;不使用万能 BO/全局 dto 包。已有公开名称不能未经迁移直接破坏。
17
+
18
+ 公开模块 DTO 的平铺、api/dto 及按能力拆分规则见 [api 包组织](api-layout.md)。只有对外契约才放 api,内部用例对象仍放 application;契约所有权相同时允许直接复用,不机械复制。
19
+
20
+ 类型选择另由 [record/class](record-vs-class.md) 定义,仅在新增类型或改变值语义、可变性时补读;沿用既有类型的字段调整不自动触发重新选型。
21
+
22
+ ## 允许复用的边界
23
+
24
+ 简单内部 CRUD,Web 和 Application 数据语义相同、无独立演进需求时 MAY 共用应用层输入/只读结果;接受校验注解带来的有限技术耦合,并记录取舍。应用对象必须归应用层,不能为了复用让 application 反向 import web。
25
+
26
+ 公开长期 API,或者同一用例被 HTTP/MQ/定时任务调用时 SHOULD 分开 Req 与 Command,以隔离绑定、安全及协议变化。字段相似不代表语义相同;HTTP 响应、模块 API DTO 和外部消息契约通常有不同演进周期。
27
+
28
+ 领域方法接收业务参数或值对象,不接收 Web Req/Application Command。不为 Application→Domain 再添加没有独立语义的 DomainDTO。
29
+
30
+ ## 写与读
31
+
32
+ 复杂写:Req → Command → Device/Imei → Repository → Converter → DeviceDO/Mapper。转换在真正需要保护的边界发生,保存语义明确为 insert/update 或带版本检查的聚合保存。
33
+
34
+ 简单 CRUD 可保留 Req/Resp/DO 作为主要对象,AppService 与 Repository 接口可在模块内部复用 DO;这是模型隔离的明确简化,不放开 Mapper/Wrapper 边界。复杂领域接口使用业务模型而非 DO。DO 不跨模块流转,不直接作为外部任意字段绑定对象。
35
+
36
+ 普通读:RepositoryImpl 内的 Mapper/SQL 可以直接投影为 DeviceListItem,通过 Repository/实际需要的查询端口返回应用层;不要求 DO→Domain→DTO。应用层不直接调用 Mapper,不重复定义语义相同的 Repository 与 QueryPort。框架 IPage/Page/Wrapper 留在适配器;对外使用自定义 PageResult,不让持久化 API 成为公共契约。
37
+
38
+ ## 值对象与映射
39
+
40
+ 值对象不可变、按值相等,并在创建时保护不变量。例如 Imei 负责业务所需的格式/校验位规则,Money 包含币种和精度;不能将只检查长度的示例宣称完整验证。
41
+
42
+ 值对象自身不依赖 MyBatis 注解或接口。TypeHandler 负责单字段 Java/数据库转换,Repository Converter 负责 DO 与领域模型的整体转换;两者不互相替代。简单 ID/状态可直接在 Converter 转换,只有确有价值时增加 TypeHandler。
43
+
44
+ 通过真实 Mapper 路径验证自定义 TypeHandler 的注册、读取、写入、null 和未知编码;复杂查询 XML 的映射不能假定跟随默认 CRUD 生效。
45
+
46
+ ## 对象构建与 Lombok
47
+
48
+ ### 拆分与构建方式
49
+
50
+ 字段多先检查职责,能形成真实业务概念时拆分;不得机械地每 3 个字段凑一组。无法合理拆分的多字段契约/查询/快照,MUST 使用有字段名的 Builder 构建,避免长串位置参数;少量字段可直接构造。通用格式与参数数量建议仅由 [编码基线](coding-style.md) 定义。
51
+
52
+ Lombok 是可选工具,Builder 是此处设计要求。已有 Lombok 时优先复用;无适配版本或不宜增加依赖时使用小型显式 Builder。不要为了 Builder 改造整个实体继承链,也不对全部 DO 一刀切禁用 Builder;先验证父类字段和实际构建路径。
53
+
54
+ ### 不变量与默认值
55
+
56
+ 所有构建入口必须保留必填、范围、组合约束、规范化和防御复制。生成的全参构造器/Builder 不能假定调用 setter;setter 有语义时追踪每条入口,不因减少样板删除承载规则的构造器。
57
+
58
+ 普通构建明确缺省值及非法组合;涉及外部输入默认值或 PATCH 时,按 [输入契约](input-contracts.md) 确定绑定语义,本节不另定义缺失/null 规则。Builder 本身不保证业务有效性或不可变性。
59
+
60
+ ### 注解选择
61
+
62
+ 注解按职责选择:DO/可变输入可用 Getter/Setter/无参构造,领域聚合不无差别 @Data 或公开 setter。审查生成 equals/hashCode、toString 与父类字段语义,敏感对象不直接打印。record 不重复生成普通 getter,泛型 Builder 推断失败时再显式给类型参数。
63
+
64
+ ### 验证构建路径
65
+
66
+ 测试实际缺省、非法组合和共享可变集合;确认生成入口没有绕过校验,不能只验证能 build。
67
+
68
+ [Builder 官方文档](https://projectlombok.org/features/Builder) 供核对生成行为;实际版本与注解处理能力以业务仓库为准。
@@ -0,0 +1,42 @@
1
+ # 枚举、常量、错误码与配置
2
+
3
+ ## 所有权
4
+
5
+ MUST 让业务类型默认归属拥有该概念的模块,而非全局 common/enums、constants、dto。
6
+
7
+ | 类型 | 示例 | 位置 |
8
+ |---|---|---|
9
+ | 内部领域状态 | DeviceLifecycleState、UpgradeRuleStatus | 所属 internal/domain/model 或 type |
10
+ | 公开模块枚举 | 由 OTA 拥有的 UpgradeChannel | 确需共享时 ota/api/type |
11
+ | 应用执行参数 | 分批处理策略 | 所属 internal/application 用例附近 |
12
+ | 技术常量 | OtaCacheKeys、MQ Topic | internal/infrastructure/cache 或 messaging |
13
+ | 业务限制 | UpgradeLimits | 领域模型/策略附近 |
14
+ | 可配置运行参数 | UpgradeProperties | internal/config 或已有配置包 |
15
+ | 业务错误/异常 | OtaErrorCode、UpgradePathConflict | 默认模块内部,公开契约需要时 api/error |
16
+ | 稳定通用技术定义 | CommonErrorCode | shared/error,且不得反向依赖业务模块 |
17
+
18
+ 目录不必细分到每类类型;一个枚举只被一个模型使用时放在同包。业务异常不能全部变为只有字符串消息的全局 BusinessException;边界处统一映射 HTTP 错误不改变业务所有权。
19
+
20
+ api/type 只承载确需公开的稳定类型,默认不再另建同义 enums 包;细化规则见 [api 包组织](api-layout.md)。
21
+
22
+ ## 编码规则
23
+
24
+ SHOULD 对新业务状态/通道采用显式稳定字符串 code,例如 online、production、running。Java 常量名可调整,外部 code 不因此改变;MUST NOT 以 ordinal 持久化,也不隐式把 name() 当作长期协议。
25
+
26
+ 数值协议、位掩码、已有系统兼容或有证据的存储需求 MAY 使用数字业务码。业务 code 与等级 level 分开,不能因为通道等级可比较就把等级充当持久化身份。
27
+
28
+ 数据库默认选可演进字符串列,长度/约束由 yx-database-design 决定;是否用原生 ENUM 结合已有数据库约定判断,不为新规范破坏存量数字码。
29
+
30
+ ## Java 与 MyBatis 的隔离
31
+
32
+ 严格领域隔离:领域 Enum 只含稳定 code 和业务行为;DO 使用 String,经 Converter/基础设施 TypeHandler 转换。不得把 @EnumValue 放到要求技术无关的领域枚举上。
33
+
34
+ 简单 CRUD 或基础设施专属枚举 MAY 使用 MyBatis-Plus 的显式枚举映射,需根据实际版本确认配置与序列化行为。数据库映射与 HTTP JSON 序列化是两个不同约定,不能配置一个就假定另一个相同。
35
+
36
+ 未知外部编码明确选择保留原值、映射显式 UNKNOWN 或拒绝并返回可理解错误;不能把未知值默认为成功/在线/已支付。严格领域恢复遇到非法持久化值应可诊断,不默默修改含义。
37
+
38
+ ## 行为、常量与共享
39
+
40
+ 稳定通道规则可由 Enum 行为表达;动态配置规则转为领域策略,不继续硬编码。业务固定限制归领域,算法保护参数归实现;随环境变化的超时/重试/批量值使用受校验配置。Redis key 用生成方法封装,不让多个用例随意拼接。
41
+
42
+ 同 JVM 确有稳定共同语义时可依赖所有者 api/type;独立部署服务优先交换字符串协议并映射本地类型。必须检查共享是否造成循环依赖。已有框架 HttpStatus/HttpHeaders 等技术定义直接复用,不重复建无价值常量。