--- name: java-development-guidelines description: 用户个人 Java 开发规范。用于用户要求遵守“我的 Java 开发规范”“java开发规范”“Java开发”“Java”，或为该用户编写、评审、重构 Java/Spring Boot 代码时。 license: MIT --- # 我的 Java 开发规范 当用户要求“遵守我的 Java 开发规范”“按我的 java 开发规范来”“使用 Java 开发规范”，或当前任务是在此用户项目中编写、评审、重构 Java / Spring Boot 代码时，使用本技能。 本规范的目标是：最小范围完成需求、保持 Java 工程结构清晰、让变更可验证，并沉淀项目内可复用经验。 ## 执行前 - 修改前先说明目标、关键假设和可验证的完成标准。 - 若需求有多种合理解释，先列出差异；只有影响实现正确性时才提问。 - 优先读取现有代码、配置、README 和测试，遵守当前项目的包结构、命名、异常处理、返回体、日志和依赖管理方式。 - 不读取、复制或输出 `.env`、Token、Cookie、认证文件、日志、缓存等敏感数据，除非用户明确授权且任务确有必要。 ## 实现原则 - 只实现用户请求的功能，不做未请求的重构、抽象或扩展。 - 修改范围保持可追溯：每一处变更都应能对应到用户需求、编译修复、测试修复或由本次变更引入的清理。 - 不顺手格式化无关文件，不删除无关死代码；如发现无关问题，在回复中说明。 - 优先使用项目已有工具类、基础响应类型、异常体系、校验方式和测试框架。 - 业务逻辑应清晰直接。只有当重复、复杂度或既有项目模式需要时，才新增抽象。 ## Java 代码规范 - 类名使用 `UpperCamelCase`，方法、变量和字段使用 `lowerCamelCase`，常量使用 `UPPER_SNAKE_CASE`。 - 新增公共 API、DTO、枚举、异常和配置项时，命名必须表达业务含义，避免 `Info`、`Data`、`Util` 等含糊命名，除非项目已有稳定约定。 - 优先使用构造器注入或项目既有注入方式；避免在业务代码中手动 `new` Spring 管理的依赖。 - 输入校验放在边界层或明确的业务校验位置，错误信息应可定位问题。 - 集合、Optional、Stream、Lambda 的使用以可读性为准，不为“函数式”牺牲调试和理解成本。 - 金额、时间、精度敏感数据使用合适类型；避免用 `double/float` 处理金额。 - 不吞异常，不打印后继续伪装成功；异常要么转成项目统一异常，要么保留上下文继续抛出。 - 日志记录关键业务上下文，不记录敏感数据，不用 `System.out.println` 替代日志框架。 ## 注释要求 - 所有新增或实质修改的类、接口和方法，都要在声明前添加多行注释或 Javadoc，说明职责；方法还应在适用时说明重要输入、输出、副作用和失败行为。 - 重要实现块或非显而易见的决策前添加单行注释，例如业务规则、复杂条件、状态流转、外部调用、数据转换、事务边界。 - 注释解释“为什么”和业务意图，不逐字复述代码。 - 新增或修改的注释使用简体中文。类名、方法名、参数名、类型等标识符可保持英文；`@param`、`@return`、`@throws` 后的说明使用简体中文。 - 不批量改写第三方代码、生成文件或本次变更范围外的既有注释。 ## Spring Boot 分层规范 Spring Boot 项目默认使用 `Controller` / `Service` / `ServiceImpl` 三层结构： ```text controller/ # Controller 类，只处理 HTTP 入参、鉴权上下文、响应封装等边界逻辑 service/ # Service 接口，定义业务能力 service/impl/ # Service 实现类，承载业务逻辑 ``` - Controller 不写核心业务逻辑，只调用 Service 接口。 - ServiceImpl 实现业务流程、校验、事务编排和外部集成协调。 - 持久化、实体、DTO、VO、配置、常量、通用响应、工具类、外部客户端等放入项目已有或命名清晰的辅助包。 - 需要参考工程约定时，可把 `C:\Users\EDY\Desktop\work\模板\IntegrateDingTalkOA` 作为风格参考，但不要盲目复制与当前项目无关的结构。 ## 测试与验证 - 修复 bug 时，优先补充能复现问题的测试，再修复并让测试通过。 - 新增业务逻辑时，按项目现有测试层级补充单元测试或集成测试；若项目没有测试基础，至少运行可用的编译、静态检查或启动前校验。 - 修改完成后运行与变更范围匹配的验证命令，例如 `mvn test`、`mvn -q test`、`mvn package`、`gradle test`、`gradle build`，并在最终回复中说明结果。 - 若验证无法运行，说明原因、已做的替代检查和剩余风险。 ## README 沉淀 - 修改前读取项目已有 `README.md`，保留结构和语言风格。 - 修改代码时同步检查本次修改范围内的 `README.md`。若变更影响接口路径、请求方法、请求体、响应体、状态码、字段含义、调用示例或配置项，必须同步更新对应文档。 - 当开发中发现可复用的项目约定、踩坑规避方式或后续必须遵守的实践时，在完成前更新 README 的相关章节。 - 记录触发条件、必须遵守的做法，以及必要时的原因或后果。 - 不写入临时调试记录、普通进度、密钥、凭据或敏感信息。