开发规范文档

本规范旨在提升项目代码质量、可维护性和团队协作效率，适用于本项目所有后端开发成员。

1. 目录结构规范

• 业务代码统一放置于 src/main/java/com/matrix/app 下，按模块分包（如 demo、partner）。
  • 响应式代码全部放在 flux 子包下
  • 阻塞式代码全部放在 mvc 子包下
• 架构代码放置于 src/main/java/com/matrix/framework 下，一般情况下无需改动
• 资源文件放置于 src/main/resources。

2. 命名规范

• 包名、文件名、类名、方法名、变量名均采用有意义的英文单词，遵循驼峰或小写加下划线风格（包名小写）。
• 类名首字母大写，方法名、变量名首字母小写。
• 常量名全部大写，单词间用下划线分隔。

3. 代码风格

• 每个类、方法、接口、重要字段需添加 Javadoc 注释，说明用途、参数、返回值、作者等。
• 逻辑分明，缩进统一为4个空格。
• 控制器、服务、数据访问层分离，禁止业务逻辑写在Controller中。
• 统一使用 Result 作为API返回包装类。
• 统一异常处理，禁止抛出未捕获的异常到前端。

4. 安全与权限

• 所有接口需根据实际情况加权限校验，敏感操作需记录审计日志。
• 用户输入需严格校验，防止SQL注入、XSS等安全问题。

5. 国际化与多语言

• 所有对用户可见的文本均需支持国际化，统一使用 I18n.getMessage 获取。

6. 低代码与扩展事件

• 通用数据操作优先使用 GenericService，如需扩展业务逻辑，采用事件接口或注解方式。
• 事件扩展类需实现对应接口并加 @Service 或 @Component 注解。

7. 配置与常驻服务

• 配置类统一放在 core/config 包下，常驻服务需实现 ILoader 接口。

8. 单元测试

• 业务逻辑需编写单元测试，测试代码放在 src/test/java 下，命名与被测类一致。

9. 代码提交与分支管理

• 提交信息需简明扼要，说明本次变更内容。
• 功能开发、修复bug等需在feature/、bugfix/等分支上进行，合并前需自测通过。

---

全局开发规范规则

1. 代码即文档：所有核心代码、接口、扩展点必须有清晰注释，便于他人理解和维护。
2. 接口幂等性：所有对外API需保证幂等性，避免重复操作带来副作用。
3. 安全优先：权限、数据校验、异常处理必须到位，严禁将敏感信息暴露给前端。
4. 模块解耦：业务模块与框架层解耦，禁止跨包直接调用内部实现。
5. 统一风格：遵循统一的代码风格和命名规范，团队成员互相review。
6. 持续集成：所有代码合并主分支前需通过自动化测试和代码检查。
7. 开箱即用：优先复用框架层能力，减少重复造轮子。
8. 国际化支持：所有用户可见内容必须支持多语言。
9. 日志与监控：关键操作需有日志，便于问题追踪和性能分析。
10. 持续优化：定期review和优化代码，保持项目健康。

本规范将根据项目实际情况持续完善，所有成员需自觉遵守。