# Java 开发通用约定

## 沟通

- 默认使用中文解释，类名、方法名和技术术语保留英文。

- 新增的java方法、类、字段都需要给出注释。

- 所有代码注释、异常消息、日志输出均使用**简体中文**。

- 所有代码和代码注释需要按照标准格式做规范化书写，需要遵守开发手册，不要全部写成一行。

- 修改前说明影响范围；完成后说明修改文件和验证结果。

- 信息不足时优先检查项目代码和配置，不凭空假设。

## 编码

- 修改前确认 Java、Spring Boot、Maven 或 Gradle 版本。

- 遵循项目现有包结构、命名和依赖注入方式。

- 优先进行最小范围修改，不顺带重构无关代码。

- 不直接编辑 target、build、generated、node_modules 中的文件。

- 不在源码、日志或配置文件中写入密码、Token、API Key。

- 新增生产依赖时说明用途、许可证和已有替代方案。

- 捕获异常时保留原始原因，不使用空 catch。

- 日志使用参数化写法，不记录敏感数据。

## Java 与 Spring

- Controller 只负责参数校验和 HTTP 响应。

- 业务逻辑放在 Service 层。

- 数据访问放在 Repository 或 DAO 层。

- 涉及多次数据库写入时检查事务边界。

- API 请求和响应优先使用 DTO/VO，不直接暴露 JPA Entity。

## 验证

- 修改后运行最相关的测试。

- Maven 项目优先使用项目自带的 mvnw 或 mvnw.cmd。

- 修复缺陷时尽可能补充回归测试。

- 如果测试无法运行，明确说明未验证内容和原因。

Java代码编写需要遵守Java开发手册。