cloudsen/eliteforge-java-coding-spec

EliteForge Java 编码规范 v1.0.0

目标

在 Java 开发任务中，依据规范提供明确的决策指引：什么应该做、什么禁止做、什么必须用什么工具/写法。引用规范条款时给出对应的 spec 行号。

执行原则

1. 命中即强制执行
   规范中标注为"禁止"的条款，任何场景都不得妥协；标注为"必须"的条款不得降级替代。

2. 代码示例优先取规范原文
   需要示例时，先从 references/java-coding-spec-v1.md 中提取对应条款的原文示例，不自行臆造。

3. 最小化加载
   先用检索定位 spec 行号，再局部读取；避免整篇加载。

4. 明确标注来源
   回答中标注对应的 spec 条款编号（如 §3.2 POJO类）。

快速检索

# 查看 spec 行号索引
cat references/toc.md

# 按关键字定位条款
rg -n "禁止|必须|推荐|使用|Spring|POJO|枚举|日志|事务|并发|MyBatis|服务间调用|Maven|国际化|网关|接口管理|工程" references/java-coding-spec-v1.md

# 按行号读取条款（示例：100-200行）
sed -n '100,200p' references/java-coding-spec-v1.md

高频问题映射

| 用户问题 | 规范条款 | 核心结论 | | ------- | ------- | -------- | | 枚举怎么写 | §3.3 | Enum后缀 + implements BizEnum + @Getter/@RequiredArgsConstructor | | POJO 类怎么写 | §3.2 | UpperCamelCase + Serializable + serialVersionUID + @Accessors(chain=true) | | 工具类用什么 | §3.4 | Apache Commons / JDK / 统一框架工具，禁止 hutool | | 日志怎么打 | §3.6 | @Slf4j + 占位符，禁止 e.printStackTrace() | | 循环里能调接口吗 | §3.5 | 禁止，必须封装批量接口 | | 线程池怎么创建 | §3.7 | ThreadPoolExecutor + TransmittableThreadLocal，禁止 Executors | | MyBatis-Plus 怎么用 | §3.8 | 禁用注解，复杂查询用 xml，keepGlobalFormat=true | | 事务怎么处理 | §3.9 | public 方法，seata TCC，围住最小必要代码 | | RestTemplate 能用吗 | §3.10 | 禁止，必须用 RestClient | | Bean 怎么注入 | §3.10 | @RequiredArgsConstructor，禁止 @Autowired | | 服务间调用用什么 | §3.11 | HttpExchangeClient + RestClient，统一框架 starter | | Maven 版本要求 | §3.12 | JDK21 + Maven 3.9.10+ + maven wrapper | | Controller 怎么分层 | §7.2/§7.3 | Param入参/Vo出参，分离 api/innerapi/openapi | | 接口路径前缀 | §7.1 | /api 前端 /inner-api 内部 /open-api 开放 | | 数据库表设计 | §4 | 主键 id + 审计字段 + tenant_id/archived/version 按需 | | 国际化文件放哪 | §7.6 | biz/resources/i18n/ | | smart-doc 配置 | §6 | smart-doc.json / smart-doc-innerapi.json / smart-doc-openapi.json | | 数据库适配 SQL 放哪 | §7.7 | resources/mapper/{mysql,dm,kingbase,oceanbase}/ |

核心约束速查

禁止清单（任何场景均不得妥协）

| 禁止项 | 必须替代 | 条款 | | ------ | -------- | ---- | | hutool | Apache Commons / JDK / 统一框架工具 | §3.4 | | e.printStackTrace() / System.out | @Slf4j + log 占位符 | §3.6 | | 循环/递归里调接口 | 批量接口封装 | §3.5 | | Executors 创建线程池 | ThreadPoolExecutor | §3.7 | | RestTemplate | Spring6 RestClient | §3.10 | | @Value 注解读 yaml | Properties 类 | §3.10 | | @Select/@Insert/@Update 注解 | MyBatis xml | §3.8 | | context-path | yaml 路由配置 | §3.10 | | lambdaQuery 多次单表查询 | xml 复杂查询 | §3.8 | | Controller 层写业务逻辑 | Manager/Service 层 | §3.10 | | @author JavaDoc | @since | §3.1 | | 覆盖方式替换框架 Configuration | 扩展类或 yaml 配置 | §3.10 |

必须清单

| 必须项 | 说明 | 条款 | | ------ | ---- | ---- | | serialVersionUID | POJO 实现 Serializable 时必须定义 | §3.2 | | @Accessors(chain=true) | Vo/Param/Dto 必须 | §3.2 | | @since | 新增内容必须标识版本 | §3.1 | | JSpecify 注解 | @Nullable/@NonNull/@NullMarked | §3.1 | | 每成员 javadoc | POJO 枚举字段必须 | §3.1/§3.2/§3.3 | | BizEnum | 前端/Entity 用枚举必须实现 | §3.3 | | ResVo<T> | Controller 和服务间调用统一响应 | §3.2/§3.11 | | HttpExchangeClient | 服务间调用必须 | §3.11 | | keepGlobalFormat=true | @TableField 必须 | §3.8 | | 函数式 wrapper | MyBatis-Plus wrapper 必须 | §3.8 | | seata TCC | 分布式事务必须 | §3.9 | | JDK21 + Maven 3.9.10+ | 必须版本 | §3.12 | | maven wrapper | 必须使用项目 wrapper | §3.12 | | 审计字段 | 业务表必须有 | §4 | | api/inner-api/open-api 前缀 | Controller 路径必须 | §7.1 | | 前端接口 Param入参/Vo出参 | Controller 必须 | §7.2 | | 内部接口 Param入参/Dto出参 | InnerController 必须 | §7.2 | | 开放接口独立 Dto/Param | OpenController 必须 | §7.2 | | 并发修改加 version | 数据库必须有乐观锁字段 | §4 |

工具链速查

| 场景 | 工具 | 条款 | | ---- | ---- | ---- | | 字符串拼接 | java.lang.String.join() | §3.4 | | 集合判空 | CollectionUtils.isEmpty() / MapUtils.isEmpty() | §3.4 | | 数组判空 | ArrayUtils.isEmpty() | §3.4 | | 字符串判空 | StringUtils.isBlank() / isNotBlank() | §3.4 | | 字符串相等 | Strings.CS.equals() / Strings.CI.equals() | §3.4 | | 二维元组 | org.apache.commons.lang3.tuple.Pair<L,R> | §3.4 | | 时间工具 | cn.cisdigital.elite.forge.infra.commons.util.TimeUtils | §3.4 | | JSON 工具 | JsonUtils | §3.4 | | 国际化 | I18nUtils | §3.4 | | 上下文 | ContextStore | §3.4 | | 服务间调用 | cisdigital-elite-forge-infra-httpexchange-spring-boot3-starter | §3.11 | | 线程上下文 | TransmittableThreadLocal + TtlExecutors | §3.7 | | 日期格式化 | DateTimeFormatter（非 SimpleDateFormat） | §3.7 |

分层模型速查

POJO 类分层

Entity    → ORM 实体映射，实现 Serializable
Dto       → 内部数据传输
Param     → Controller 入参，必须 jsr 303 validation
Vo        → Controller 出参

各层入参出参约束

| 层级 | 入参 | 出参 | | ---- | ---- | ---- | | repository | Param / Dto | Entity / Dto | | service | Param / Dto | Dto / Vo | | 前端接口 Controller | Param | Vo | | 内部接口 InnerController | Param | Dto | | 开放接口 OpenController | Param | Dto |

Maven 模块结构

<service>-model        POJO + MapStruct
<service>-client       HttpExchangeClient 接口定义
<service>-xxx-starter  业务相关 starter
<service>-xxx-sdk      业务相关 sdk
<service>-biz          业务模块（controller/service/repository）
<service>-boot         启动模块

biz 代码分层

- biz/common/exception
- biz/common/util
- biz/模块A/controller/{innerapi, api, openapi}
- biz/模块A/service/xxxService
- biz/模块A/repository/{mapper/xxxMapper, xxxRepository}

接口路径前缀

• /api → 前端接口（需网关鉴权）
• /inner-api → 服务间内部调用（无需鉴权）
• /open-api → 开放接口（需开放平台鉴权）

输出约束

• 回答时必须标注规范条款编号（§章节号）
• 涉及代码示例时，从 references/java-coding-spec-v1.md 对应条款提取，不自行编写
• 涉及框架/工具选型时，优先引用统一框架能力，参见 eliteforge-framework-specification
• 涉及版本号时引用规范原文，不臆造具体版本
• 规范未覆盖的场景，标注"需用户补充或需外部确认"

参考资料

• 规范全文（行号索引）：references/toc.md
• 规范全文：references/java-coding-spec-v1.md