minglei/SKILL.md

---

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 三层结构：

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 的相关章节。
• 记录触发条件、必须遵守的做法，以及必要时的原因或后果。
• 不写入临时调试记录、普通进度、密钥、凭据或敏感信息。