Objectives
In Java development tasks, provide clear decision guidance based on the standards: what should be done, what is prohibited, and what tools/writing style must be used. When citing standard clauses, provide the corresponding spec line number.
Execution Principles
-
Mandatory when matched
Clauses marked as "prohibited" in the standards must not be compromised under any circumstances; clauses marked as "must" must not be replaced with downgraded alternatives. -
Prefer the original text of the standards for code examples
When examples are needed, first extract the original example for the corresponding clause fromreferences/java-coding-spec-v1.md, and do not make one up yourself. -
Minimize loading
First use retrieval to locate the spec line number, then read locally; avoid loading the entire document. -
Clearly indicate the source
In the answer, indicate the corresponding spec clause number (such as§3.2 POJO类）。
Quick retrieval
# 查看 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
High-frequency question mapping
| User question | Standard clause | Core conclusion |
|---|---|---|
| How to write an enum | §3.3 | Enum suffix + implements BizEnum + @Getter/@RequiredArgsConstructor |
| How to write a POJO class | §3.2 | UpperCamelCase + Serializable + serialVersionUID + @Accessors(chain=true) |
| What to use for utility classes | §3.4 | Apache Commons / JDK / unified framework utilities, hutool is prohibited |
| How to log | §3.6 | @Slf4j + placeholders, e.printStackTrace() is prohibited |
| Can interfaces be called inside a loop | §3.5 | Prohibited, batch interfaces must be encapsulated |
| How to create a thread pool | §3.7 | ThreadPoolExecutor + TransmittableThreadLocal, Executors is prohibited |
| How to use MyBatis-Plus | §3.8 | Annotations are prohibited, use xml for complex queries, keepGlobalFormat=true |
| How to handle transactions | §3.9 | public methods, seata TCC, wrap only the minimum necessary code |
| Can RestTemplate be used | §3.10 | Prohibited, RestClient must be used |
| How to inject a Bean | §3.10 | @RequiredArgsConstructor, @Autowired is prohibited |
| What to use for inter-service calls | §3.11 | HttpExchangeClient + RestClient, unified framework starter |
| Maven version requirements | §3.12 | JDK21 + Maven 3.9.10+ + maven wrapper |
| How to layer a Controller | §7.2/§7.3 | Param for input/Vo for output, separate api/innerapi/openapi |
| API path prefixes | §7.1 | /api frontend /inner-api internal /open-api open |
| Database table design | §4 | Primary key id + audit fields + tenant_id/archived/version as needed |
| Where to put internationalization files | §7.6 | biz/resources/i18n/ |
| smart-doc configuration | §6 | smart-doc.json / smart-doc-innerapi.json / smart-doc-openapi.json |
| Where to put database-adapted SQL | §7.7 | resources/mapper/{mysql,dm,kingbase,oceanbase}/ |
Core Constraints Quick Reference
Prohibited list (must not be compromised under any circumstances)
| Prohibited item | Required replacement | Clause |
|---|---|---|
| hutool | Apache Commons / JDK / unified framework utilities | §3.4 |
| e.printStackTrace() / System.out | @Slf4j + log placeholders | §3.6 |
| Calling APIs in loops/recursion | Batch API encapsulation | §3.5 |
| Executors creating thread pools | ThreadPoolExecutor | §3.7 |
| RestTemplate | Spring6 RestClient | §3.10 |
| @Value annotation to read yaml | Properties class | §3.10 |
| @Select/@Insert/@Update annotations | MyBatis xml | §3.8 |
| context-path | yaml routing configuration | §3.10 |
| lambdaQuery multiple single-table queries | xml complex queries | §3.8 |
| Writing business logic in the Controller layer | Manager/Service layer | §3.10 |
| @author JavaDoc | @since | §3.1 |
| Replacing framework Configuration by overriding | Extension classes or yaml configuration | §3.10 |
Mandatory Checklist
| Mandatory Item | Description | Clause |
|---|---|---|
| serialVersionUID | Must be defined when a POJO implements Serializable | §3.2 |
| @Accessors(chain=true) | Vo/Param/Dto required | §3.2 |
| @since | New content must have a version identifier | §3.1 |
| JSpecify annotations | @Nullable/@NonNull/@NullMarked | §3.1 |
| Javadoc for each member | POJO enum fields required | §3.1/§3.2/§3.3 |
| BizEnum | Enums used for frontend/Entity must implement | §3.3 |
| ResVo | Unified response for calls between Controller and services | §3.2/§3.11 |
| HttpExchangeClient | Required for service-to-service calls | §3.11 |
| keepGlobalFormat=true | @TableField required | §3.8 |
| Functional wrapper | MyBatis-Plus wrapper required | §3.8 |
| seata TCC | Distributed transactions required | §3.9 |
| JDK21 + Maven 3.9.10+ | Version required | §3.12 |
| maven wrapper | Must use the project wrapper | §3.12 |
| Audit fields | Business tables must have | §4 |
| api/inner-api/open-api prefix | Controller path required | §7.1 |
| Frontend API Param input/Vo output | Controller required | §7.2 |
| Internal API Param input/Dto output | InnerController required | §7.2 |
| Open API independent Dto/Param | OpenController required | §7.2 |
| Add version for concurrent modifications | The database must have an optimistic lock field | §4 |
Toolchain Quick Reference
| Scenario | Tool | Clause |
|---|---|---|
| String concatenation | java.lang.String.join() |
§3.4 |
| Collection null/empty check | CollectionUtils.isEmpty() / MapUtils.isEmpty() |
§3.4 |
| Array null/empty check | ArrayUtils.isEmpty() |
§3.4 |
| String null/empty 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 |
| Service-to-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 Class Layering
Entity → ORM 实体映射，实现 Serializable
Dto → 内部数据传输
Param → Controller 入参，必须 jsr 303 validation
Vo → Controller 出参
Input/Output Parameter Constraints for Each Layer
| Layer | Input Parameter | Output Parameter |
|---|---|---|
| repository | Param / Dto | Entity / Dto |
| service | Param / Dto | Dto / Vo |
| Frontend API Controller | Param | Vo |
| Internal API InnerController | Param | Dto |
| Open API OpenController | Param | Dto |
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 启动模块
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}
API Path Prefixes
/api→ Frontend API (requires gateway authentication)/inner-api→ Service-to-service internal call (no authentication required)/open-api→ Open API (requires open platform authentication)
Output Constraints
- When answering, the applicable specification clause number must be cited (§chapter number)
- When code examples are involved, extract them from
references/java-coding-spec-v1.mdcorresponding clauses; do not write them yourself - When framework/tool selection is involved, prioritize citing unified framework capabilities; see
eliteforge-framework-specification - When version numbers are involved, cite the original specification text; do not fabricate specific versions
- For scenarios not covered by the specification, mark "requires user supplementation or external confirmation"
Reference materials
- Full specification text (line number index):
references/toc.md - Full specification text:
references/java-coding-spec-v1.md