java-spring-boot-ddd-example

Imported from Redlotus794/java-spring-boot-ddd-example (AGENTS.md). Install upstream with npx skills add Redlotus794/java-spring-boot-ddd-example. Copyright stays with the author.

{{项目名称}} 项目文档

项目元信息 (Project Context)

使用中文管理项目的文档，必要的专有名词可以添加英文（或直接使用）

项目基本信息

• 项目名称:
• 全称:
• 描述:
• 语言: 中文/Chinese，必要时可以使用英文
• Swagger地址: ${PROJECT_SERVER}/swagger-ui.html#
• 依赖管理: maven 3.5.4
• 技术栈：
  • 编程语言: Java 8
  • 框架: Spring Boot 2.0.7.RELEASE, Spring MVC
  • 数据库: MySQL 5.7
• 架构风格: DDD、分层架构

核心价值

• 描述项目的价值所在

2. 命令集 (Commands)

启动服务

测试命令

前置：如果存在

3. 项目结构 (Project Structure)

java-spring-boot-ddd-example
├── AGENTS.md
│   └── AI 协作约束、项目结构和工程规范说明
├── pom.xml
│   └── Maven 构建入口，管理依赖、插件和打包流程
├── README.md
│   └── 项目说明、运行方式和基础使用指引
├── docs
│   ├── ai
│   │   └── AI 协作资料与提示词文档
│   ├── archive
│   │   └── 历史归档资料，保留旧版本或废弃文档
│   ├── development
│   │   ├── architecture
│   │   │   └── 架构设计文档，说明系统分层和设计决策
│   │   ├── convention
│   │   │   └── 开发约定文档，统一代码、接口和协作规范
│   │   └── openapi
│   │       └── OpenAPI 相关产物，如规范文件、示例和渲染结果
│   ├── ops
│   │   ├── deployment
│   │   │   └── 部署文档与发布说明
│   │   └── scripts
│   │       └── 运维脚本，支持部署、备份、监控和维护
│   ├── project-managament
│   │   └── 项目管理资料，覆盖计划、会议纪要、流程、风险和路线图
│   ├── requirements
│   │   └── 需求文档，包含产品需求、技术需求、原型和待办
│   ├── template
│   │   └── 文档模板与配置模板
│   └── test
│       └── 测试文档目录，包含测试计划、测试用例和测试报告
├── src
│   ├── main
│   │   ├── java/com/rdlts/jsbs/ddd
│   │   │   ├── applicationservice
│   │   │   │   └── 应用服务层，负责用例编排和事务边界控制
│   │   │   ├── domain
│   │   │   │   ├── aggregate
│   │   │   │   │   └── 聚合根与聚合边界，维护核心业务一致性
│   │   │   │   ├── entity
│   │   │   │   │   └── 领域实体，表达具有身份和生命周期的业务对象
│   │   │   │   └── valueobject
│   │   │   │       └── 值对象，表达不可变且无身份的业务概念
│   │   │   ├── infrastructure
│   │   │   │   ├── repository
│   │   │   │   │   └── 仓储实现，负责领域对象持久化和查询
│   │   │   │   └── 基础设施层，封装数据库、中间件和外部系统接入
│   │   │   └── userinterface
│   │   │       └── 接口层，负责 Controller、请求参数和响应对象
│   │   └── resources
│   │       └── 运行时资源目录，通常存放配置文件和静态资源
│   └── test
│       ├── java
│       │   └── 测试代码目录，存放单元测试和集成测试
│       └── resources
│           ├── data
│           │   └── 测试数据样例
│           ├── documents
│           │   └── 测试使用的文档资源
│           └── images
│               └── 测试使用的图片资源
└── target
    └── Maven 构建输出目录，存放编译、测试和打包产物

4. 代码规范

命名规范

• 包名: 全小写，按技术分层和业务语义组织，如 com.rdlts.jsbs.ddd.domain.aggregate
• 类名 / 接口名: 使用大驼峰命名法，如 Order, OrderRepository, CreateOrderCommand
• 方法名 / 变量名: 使用小驼峰命名法，如 createOrder, orderId, loadOrder
• 常量名: 全大写加下划线，如 MAX_RETRY_COUNT
• 布尔方法 / 字段: 优先使用 is、has、can 等前缀，如 isPaid()
• DTO / Command / Query / Event: 名称必须体现用途和边界，避免使用 Data、Info 这类泛化命名

注释规范

• 优先自解释代码: 通过清晰命名、合理拆分方法和对象表达意图，避免用注释弥补糟糕设计
• 类注释: 仅在类职责、领域语义、约束条件或设计动机不明显时补充
• 方法注释: 仅在涉及事务、副作用、边界条件、异常语义或跨系统交互时补充
• 字段注释: 用于说明业务含义、单位、格式、枚举约束和兼容性要求
• 接口文档: 对外 API、消息事件和第三方集成点需说明输入、输出、错误语义和幂等要求
• 禁止无效注释: 不写“给变量赋值”“调用某方法”这类重复代码表意的注释

设计原则

1. 分层清晰: 严格遵守 userinterface -> applicationservice -> domain -> infrastructure 的职责划分和依赖方向
2. 领域优先: 核心业务规则应沉淀在领域模型中，不放在 Controller、DTO 或 Repository 实现里
3. 聚合封装: 聚合根负责维护一致性和状态变更，外部对象不得绕过聚合直接修改内部实体
4. 单一职责: Controller 处理协议转换，Application Service 编排用例，Domain 处理业务规则，Infrastructure 处理技术实现
5. 面向抽象: 应用层和领域层依赖接口，基础设施层负责具体实现
6. 避免贫血模型: 实体和值对象不只是数据容器，应承载与自身职责相关的行为和约束
7. 边界明确: 跨聚合操作通过应用服务协调，避免实体之间形成复杂双向依赖

分层约束

• userinterface 层: 负责 Controller、参数接收、响应转换和接口协议适配，不承载核心业务逻辑
• applicationservice 层: 负责用例编排、事务边界、权限校验和调用顺序控制，不直接编写持久化细节
• domain 层: 负责实体、聚合、值对象、领域服务和仓储抽象，是业务规则核心
• infrastructure 层: 负责仓储实现、ORM、消息、外部服务客户端和技术配置，不反向侵入领域模型

Java / Spring 约定

• 优先使用构造器注入，避免字段注入
• 明确访问控制，默认使用 private，仅在确有需要时放宽可见性
• 谨慎使用 Lombok；只有在不削弱语义表达、调试体验和可维护性时使用
• 方法应短小且职责单一，参数过多时优先封装为命令对象或值对象
• 使用 Jakarta Validation 或等效机制对外部输入进行校验，校验规则尽量靠近接口边界
• 事务边界优先定义在应用服务层，避免在 Controller 或 Repository 层随意扩散事务注解
• equals()、hashCode()、toString() 的实现必须符合对象语义，值对象尤其需要保持一致性
• 避免返回 null 表达可选结果，优先使用明确的空集合、异常或 Optional 表达语义

异常处理

• 业务异常与系统异常分离，业务异常表示规则不满足，系统异常表示技术故障
• 统一异常处理入口，对外返回稳定、可理解的错误码和错误信息
• 捕获异常时必须补充上下文、转换语义或完成兜底处理，禁止无意义吞异常
• 日志应记录排障所需关键信息，但不得输出密码、令牌、证件号等敏感数据

5. 测试要求 (Testing)

测试框架

• 使用 mvn test 作为标准测试入口，确保本地与 CI 执行方式一致
• 单元测试基于 JUnit 5，必要时配合 Mockito 进行依赖隔离
• Spring 集成测试使用 Spring Boot Test
• 测试类命名建议为 *Test、*Tests；集成测试可使用 *IT
• 测试方法命名应体现业务意图和预期结果，如 shouldCreateOrderWhenCommandIsValid

测试命令

• 执行单元测试: mvn test
• 执行完整校验: mvn clean test
• 生成覆盖率报告: mvn clean test jacoco:report
• 如项目启用集成测试生命周期，可使用 mvn verify

测试报告

• Maven Surefire 测试结果目录: target/surefire-reports/
• JaCoCo XML 报告目录: target/site/jacoco/jacoco.xml
• JaCoCo HTML 报告目录: target/site/jacoco/index.html
• 测试输出应包含失败用例、异常堆栈、执行统计和覆盖率结果，便于本地排障和 CI 分析

测试类型

1. 单元测试: 聚焦领域对象、值对象、领域服务和应用服务中的单一职责逻辑
2. 集成测试: 验证仓储实现、数据库映射、Spring 配置装配和模块协作
3. 接口测试: 验证 Controller 的参数校验、状态码、响应结构和错误处理
4. 端到端测试: 在必要时覆盖关键业务链路，验证系统级行为

测试覆盖率

• 使用 JaCoCo 生成覆盖率报告，并纳入本地检查与 CI 校验
• 核心业务模块建议行覆盖率不低于 80%
• 关键领域规则、聚合行为、应用服务编排和异常分支必须有测试用例覆盖
• 新增功能或修复缺陷时，应同时补充回归测试，避免问题重复出现

测试约束

• 单元测试应具备可重复执行性，不依赖外部环境的随机状态
• 测试数据应最小化并显式表达业务含义，避免在测试中堆积无关样板
• 一个测试只验证一个核心行为，失败原因应清晰可定位
• 除非明确验证集成行为，单元测试中应避免直接访问数据库、网络和外部中间件
• 提交前至少执行一次 mvn test，确保测试通过且报告可生成

6. 边界和安全

边界处理

• 输入参数验证: 对所有外部输入进行严格验证
• 超时处理: 设置合理的超时时间，避免阻塞
• 资源限制: 控制并发数和资源使用
• 异常边界: 处理各种异常情况

安全措施

描述AI可以做的事，以及不能做的事，边界和安全措施是什么，如何处理异常和边界情况等

1. 配置安全:
   • 使用Apollo配置中心管理敏感配置
   • 配置文件中不得存储明文密码和密钥
2. 数据安全:
   • 敏感数据加密存储
   • 数据传输使用HTTPS
3. 访问控制:
   • 接口访问认证
   • 权限管理
4. 日志安全:
   • 日志中不得包含敏感信息
   • 日志访问控制
5. 依赖安全:
   • 定期更新依赖库
   • 检查依赖库的安全漏洞

贡献指南

• 遵循代码规范和设计原则
• 编写完善的测试用例
• 提交前确保所有测试通过
• 详细的提交信息描述