Appearance

规范说明 ​

目的 ​

《ECShopX Java 技术说明文档》中的规范篇面向二次开发工程师，统一模块命名、代码风格、数据库与 Redis 使用、Git 提交等团队约定，目标是：

  • 高效编码 — 减少「该放哪、叫什么」的决策时间；
  • 风格统一 — 多 Bundle 并行开发时，代码结构可预期；
  • 减少错误 — 降低分层越界、配置误用等常见问题；
  • 可维护 — 与脚手架、代码评审、CI 检查对齐。

规范以 ecshopx-java 仓库为准。

Java 规范索引 ​

章节说明
模块命名规范Maven 模块 ecshopx-<domain>、包名与类命名
基本代码规范包结构、分层、空指针、日志
API 控制器规范REST 控制器职责与禁止事项
配置与环境变量application.properties / application-local.properties / APP_ARGS
Git 提交规范Conventional Commits
MySQL 规范建表、索引、SQL 规约
Redis 开发规范Key 设计、命令与客户端约定

缓存相关约定见 应用缓存、网关缓存摘要。

开发哲学 ​

规范无法覆盖每一行代码的写法，以下原则作为决策时的「指明灯」：

  • DRY — Don't Repeat Yourself，不写重复业务逻辑；
  • 约定优于配置 — 优先采用 Spring Boot / 本仓库既有分层，不过度自定义框架；
  • KISS — 保持简单可读，避免过度设计；
  • 官方与主厨精选 — 优先 Spring、MyBatis-Plus、XXL-JOB 等官方推荐用法与本仓库已验证模式。

设计理念 ​

  • 分层 MVC + 领域服务 — api（Controller）→ service → repository / mapper → domain；跨模块通过 Port 或 dispatch 事件，禁止 Bundle 间直接依赖对方 Mapper。
  • RESTful — 资源化 URL 与标准 HTTP 动词；管理端与前台分路径前缀，详见 路由与 API 分组。

相关章节 ​