Back to Details

eliteforge-java-coding-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EliteForge Java 编码规范 v1.0.0

EliteForge Java Coding Specification v1.0.0

目标

Goal

在 Java 开发任务中，依据规范提供明确的决策指引：什么应该做、什么禁止做、什么必须用什么工具/写法。引用规范条款时给出对应的 spec 行号。
Provide clear decision guidance in Java development tasks: what should be done, what is prohibited, what tools/writing methods must be used. When citing specification clauses, provide the corresponding spec line number.

执行原则

Execution Principles

  1. 命中即强制执行
    规范中标注为"禁止"的条款，任何场景都不得妥协；标注为"必须"的条款不得降级替代。
  2. 代码示例优先取规范原文
    需要示例时，先从 
    references/java-coding-spec-v1.md
    中提取对应条款的原文示例，不自行臆造。
  3. 最小化加载
    先用检索定位 spec 行号，再局部读取；避免整篇加载。
  4. 明确标注来源
    回答中标注对应的 spec 条款编号（如 
    §3.2 POJO类
    ）。
  1. Enforce immediately when applicable
    Clauses marked as "Prohibited" in the specification must not be compromised in any scenario; clauses marked as "Mandatory" must not be replaced with lower-level alternatives.
  2. Prioritize original specification examples for code samples
    When examples are needed, first extract the original example of the corresponding clause from 
    references/java-coding-spec-v1.md
    , do not create examples arbitrarily.
  3. Minimize loading
    First locate the spec line number via search, then read locally; avoid loading the entire document.
  4. Clearly mark the source
    Mark the corresponding spec clause number in the answer (e.g., 
    §3.2 POJO Classes
    ).

快速检索

Quick Search

bash
undefined
bash
undefined

查看 spec 行号索引

View spec line number index

cat references/toc.md
cat references/toc.md

按关键字定位条款

Locate clauses by keywords

rg -n "禁止|必须|推荐|使用|Spring|POJO|枚举|日志|事务|并发|MyBatis|服务间调用|Maven|国际化|网关|接口管理|工程" references/java-coding-spec-v1.md
rg -n "Prohibited|Mandatory|Recommended|Use|Spring|POJO|Enum|Logging|Transaction|Concurrency|MyBatis|Inter-service Call|Maven|Internationalization|Gateway|Interface Management|Project" references/java-coding-spec-v1.md

按行号读取条款（示例：100-200行）

Read clauses by line number (example: lines 100-200)

sed -n '100,200p' references/java-coding-spec-v1.md
undefined
sed -n '100,200p' references/java-coding-spec-v1.md
undefined

高频问题映射

High-Frequency Problem Mapping

用户问题规范条款核心结论
枚举怎么写§3.3Enum后缀 + implements BizEnum + @Getter/@RequiredArgsConstructor
POJO 类怎么写§3.2UpperCamelCase + Serializable + serialVersionUID + @Accessors(chain=true)
工具类用什么§3.4Apache Commons / JDK / 统一框架工具，禁止 hutool
日志怎么打§3.6@Slf4j + 占位符，禁止 e.printStackTrace()
循环里能调接口吗§3.5禁止，必须封装批量接口
线程池怎么创建§3.7ThreadPoolExecutor + TransmittableThreadLocal，禁止 Executors
MyBatis-Plus 怎么用§3.8禁用注解，复杂查询用 xml，keepGlobalFormat=true
事务怎么处理§3.9public 方法，seata TCC，围住最小必要代码
RestTemplate 能用吗§3.10禁止，必须用 RestClient
Bean 怎么注入§3.10@RequiredArgsConstructor，禁止 @Autowired
服务间调用用什么§3.11HttpExchangeClient + RestClient，统一框架 starter
Maven 版本要求§3.12JDK21 + Maven 3.9.10+ + maven wrapper
Controller 怎么分层§7.2/§7.3Param入参/Vo出参，分离 api/innerapi/openapi
接口路径前缀§7.1/api 前端 /inner-api 内部 /open-api 开放
数据库表设计§4主键 id + 审计字段 + tenant_id/archived/version 按需
国际化文件放哪§7.6biz/resources/i18n/
smart-doc 配置§6smart-doc.json / smart-doc-innerapi.json / smart-doc-openapi.json
数据库适配 SQL 放哪§7.7resources/mapper/{mysql,dm,kingbase,oceanbase}/
User QuestionSpecification ClauseCore Conclusion
How to write enums§3.3Enum suffix + implements BizEnum + @Getter/@RequiredArgsConstructor
How to write POJO classes§3.2UpperCamelCase + Serializable + serialVersionUID + @Accessors(chain=true)
What utility classes to use§3.4Apache Commons / JDK / unified framework tools, hutool is prohibited
How to log§3.6@Slf4j + placeholders, e.printStackTrace() is prohibited
Can interfaces be called in loops?§3.5Prohibited, batch interfaces must be encapsulated
How to create thread pools§3.7ThreadPoolExecutor + TransmittableThreadLocal, Executors is prohibited
How to use MyBatis-Plus§3.8Disable annotations, use xml for complex queries, keepGlobalFormat=true
How to handle transactions§3.9Public methods, seata TCC, wrap the minimum necessary code
Can RestTemplate be used?§3.10Prohibited, RestClient must be used
How to inject Beans§3.10@RequiredArgsConstructor, @Autowired is prohibited
What to use for inter-service calls§3.11HttpExchangeClient + RestClient, unified framework starter
Maven version requirements§3.12JDK21 + Maven 3.9.10+ + maven wrapper
How to layer Controllers§7.2/§7.3Param for input/Vo for output, separate api/innerapi/openapi
Interface path prefix§7.1/api for frontend /inner-api for internal /open-api for external
Database table design§4Primary key id + audit fields + tenant_id/archived/version as needed
Where to place internationalization files§7.6biz/resources/i18n/
smart-doc configuration§6smart-doc.json / smart-doc-innerapi.json / smart-doc-openapi.json
Where to place database-adapted SQL§7.7resources/mapper/{mysql,dm,kingbase,oceanbase}/

核心约束速查

Core Constraint Quick Reference

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

Prohibited List (No compromise in any scenario)

禁止项必须替代条款
hutoolApache Commons / JDK / 统一框架工具§3.4
e.printStackTrace() / System.out@Slf4j + log 占位符§3.6
循环/递归里调接口批量接口封装§3.5
Executors 创建线程池ThreadPoolExecutor§3.7
RestTemplateSpring6 RestClient§3.10
@Value 注解读 yamlProperties 类§3.10
@Select/@Insert/@Update 注解MyBatis xml§3.8
context-pathyaml 路由配置§3.10
lambdaQuery 多次单表查询xml 复杂查询§3.8
Controller 层写业务逻辑Manager/Service 层§3.10
@author JavaDoc@since§3.1
覆盖方式替换框架 Configuration扩展类或 yaml 配置§3.10
Prohibited ItemMandatory AlternativeClause
hutoolApache Commons / JDK / unified framework tools§3.4
e.printStackTrace() / System.out@Slf4j + log placeholders§3.6
Calling interfaces in loops/recursionBatch interface encapsulation§3.5
Creating thread pools with ExecutorsThreadPoolExecutor§3.7
RestTemplateSpring6 RestClient§3.10
Reading yaml with @Value annotationProperties class§3.10
@Select/@Insert/@Update annotationsMyBatis xml§3.8
context-pathyaml route configuration§3.10
Multiple single-table queries with lambdaQueryxml complex queries§3.8
Writing business logic in Controller layerManager/Service layer§3.10
@author JavaDoc@since§3.1
Replacing framework Configuration via overrideExtension class or yaml configuration§3.10

必须清单

Mandatory List

必须项说明条款
serialVersionUIDPOJO 实现 Serializable 时必须定义§3.2
@Accessors(chain=true)Vo/Param/Dto 必须§3.2
@since新增内容必须标识版本§3.1
JSpecify 注解@Nullable/@NonNull/@NullMarked§3.1
每成员 javadocPOJO 枚举字段必须§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
函数式 wrapperMyBatis-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/ParamOpenController 必须§7.2
并发修改加 version数据库必须有乐观锁字段§4
Mandatory ItemDescriptionClause
serialVersionUIDMust be defined when POJO implements Serializable§3.2
@Accessors(chain=true)Mandatory for Vo/Param/Dto§3.2
@sinceMust mark version for new content§3.1
JSpecify annotations@Nullable/@NonNull/@NullMarked§3.1
Javadoc for each memberMandatory for POJO enum fields§3.1/§3.2/§3.3
BizEnumMust be implemented for enums used in frontend/Entity§3.3
ResVo<T>Unified response for Controller and inter-service calls§3.2/§3.11
HttpExchangeClientMandatory for inter-service calls§3.11
keepGlobalFormat=trueMandatory for @TableField§3.8
Functional wrapperMandatory for MyBatis-Plus wrapper§3.8
seata TCCMandatory for distributed transactions§3.9
JDK21 + Maven 3.9.10+Mandatory versions§3.12
maven wrapperMust use project wrapper§3.12
Audit fieldsMust exist in business tables§4
api/inner-api/open-api prefixMandatory for Controller paths§7.1
Param input/Vo output for frontend interfacesMandatory for Controller§7.2
Param input/Dto output for internal interfacesMandatory for InnerController§7.2
Independent Dto/Param for external interfacesMandatory for OpenController§7.2
Add version for concurrent modificationsMust have optimistic lock field in database§4

工具链速查

Toolchain Quick Reference

场景工具条款
字符串拼接
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
ScenarioToolClause
String concatenation
java.lang.String.join()
§3.4
Collection null check
CollectionUtils.isEmpty()
/ 
MapUtils.isEmpty()
§3.4
Array null check
ArrayUtils.isEmpty()
§3.4
String null check
StringUtils.isBlank()
/ 
isNotBlank()
§3.4
String equality
Strings.CS.equals()
/ 
Strings.CI.equals()
§3.4
Two-dimensional tuple
org.apache.commons.lang3.tuple.Pair<L,R>
§3.4
Time utility
cn.cisdigital.elite.forge.infra.commons.util.TimeUtils
§3.4
JSON utility
JsonUtils
§3.4
Internationalization
I18nUtils
§3.4
Context
ContextStore
§3.4
Inter-service calls
cisdigital-elite-forge-infra-httpexchange-spring-boot3-starter
§3.11
Thread context
TransmittableThreadLocal
+ 
TtlExecutors
§3.7
Date formatting
DateTimeFormatter
(not SimpleDateFormat)		§3.7

分层模型速查

Layered Model Quick Reference

POJO 类分层

POJO Class Layering

Entity    → ORM 实体映射，实现 Serializable
Dto       → 内部数据传输
Param     → Controller 入参，必须 jsr 303 validation
Vo        → Controller 出参
Entity    → ORM entity mapping, implements Serializable
Dto       → Internal data transmission
Param     → Controller input, must use jsr 303 validation
Vo        → Controller output

各层入参出参约束

Input/Output Constraints for Each Layer

层级入参出参
repositoryParam / DtoEntity / Dto
serviceParam / DtoDto / Vo
前端接口 ControllerParamVo
内部接口 InnerControllerParamDto
开放接口 OpenControllerParamDto
LayerInputOutput
repositoryParam / DtoEntity / Dto
serviceParam / DtoDto / Vo
Frontend Interface ControllerParamVo
Internal Interface InnerControllerParamDto
External Interface OpenControllerParamDto

Maven 模块结构

Maven Module Structure

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

biz 代码分层

biz Code Layering

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

接口路径前缀

Interface Path Prefix

  • /api
    → 前端接口（需网关鉴权）
  • /inner-api
    → 服务间内部调用（无需鉴权）
  • /open-api
    → 开放接口（需开放平台鉴权）
  • /api
    → Frontend interfaces (require gateway authentication)
  • /inner-api
    → Internal inter-service calls (no authentication required)
  • /open-api
    → External interfaces (require open platform authentication)

输出约束

Output Constraints

  • 回答时必须标注规范条款编号（§章节号）
  • 涉及代码示例时，从 
    references/java-coding-spec-v1.md
    对应条款提取，不自行编写
  • 涉及框架/工具选型时，优先引用统一框架能力，参见 
    eliteforge-framework-specification
  • 涉及版本号时引用规范原文，不臆造具体版本
  • 规范未覆盖的场景，标注"需用户补充或需外部确认"
  • Must mark the specification clause number (§chapter number) when answering
  • When involving code examples, extract from the corresponding clause in 
    references/java-coding-spec-v1.md
    , do not write your own
  • When involving framework/tool selection, prioritize referencing unified framework capabilities, see 
    eliteforge-framework-specification
  • When involving version numbers, reference the original specification, do not fabricate specific versions
  • For scenarios not covered by the specification, mark "Need user supplement or external confirmation"

参考资料

Reference Materials

  • 规范全文（行号索引）：
    references/toc.md
  • 规范全文：
    references/java-coding-spec-v1.md
  • Full specification (line number index): 
    references/toc.md
  • Full specification: 
    references/java-coding-spec-v1.md