EliteForge Java Coding Specification v1.0.0

Goal

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

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.
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.
Minimize loading
First locate the spec line number via search, then read locally; avoid loading the entire document.
Clearly mark the source
Mark the corresponding spec clause number in the answer (e.g.,
```
§3.2 POJO Classes
```
).

Quick Search

bash

# View spec line number index
cat references/toc.md

# Locate clauses by keywords
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

# Read clauses by line number (example: lines 100-200)
sed -n '100,200p' references/java-coding-spec-v1.md

High-Frequency Problem Mapping

User Question	Specification Clause	Core Conclusion
How to write enums	§3.3	Enum suffix + implements BizEnum + @Getter/@RequiredArgsConstructor
How to write POJO classes	§3.2	UpperCamelCase + Serializable + serialVersionUID + @Accessors(chain=true)
What utility classes to use	§3.4	Apache 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.5	Prohibited, batch interfaces must be encapsulated
How to create thread pools	§3.7	ThreadPoolExecutor + TransmittableThreadLocal, Executors is prohibited
How to use MyBatis-Plus	§3.8	Disable annotations, use xml for complex queries, keepGlobalFormat=true
How to handle transactions	§3.9	Public methods, seata TCC, wrap the minimum necessary code
Can RestTemplate be used?	§3.10	Prohibited, RestClient must be used
How to inject Beans	§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 Controllers	§7.2/§7.3	Param 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	§4	Primary key id + audit fields + tenant_id/archived/version as needed
Where to place internationalization files	§7.6	biz/resources/i18n/
smart-doc configuration	§6	smart-doc.json / smart-doc-innerapi.json / smart-doc-openapi.json
Where to place database-adapted SQL	§7.7	resources/mapper/{mysql,dm,kingbase,oceanbase}/

Core Constraint Quick Reference

Prohibited List (No compromise in any scenario)

Prohibited Item	Mandatory Alternative	Clause
hutool	Apache Commons / JDK / unified framework tools	§3.4
e.printStackTrace() / System.out	@Slf4j + log placeholders	§3.6
Calling interfaces in loops/recursion	Batch interface encapsulation	§3.5
Creating thread pools with Executors	ThreadPoolExecutor	§3.7
RestTemplate	Spring6 RestClient	§3.10
Reading yaml with @Value annotation	Properties class	§3.10
@Select/@Insert/@Update annotations	MyBatis xml	§3.8
context-path	yaml route configuration	§3.10
Multiple single-table queries with lambdaQuery	xml complex queries	§3.8
Writing business logic in Controller layer	Manager/Service layer	§3.10
@author JavaDoc	@since	§3.1
Replacing framework Configuration via override	Extension class or yaml configuration	§3.10

Mandatory List

Mandatory Item	Description	Clause
serialVersionUID	Must be defined when POJO implements Serializable	§3.2
@Accessors(chain=true)	Mandatory for Vo/Param/Dto	§3.2
@since	Must mark version for new content	§3.1
JSpecify annotations	@Nullable/@NonNull/@NullMarked	§3.1
Javadoc for each member	Mandatory for POJO enum fields	§3.1/§3.2/§3.3
BizEnum	Must be implemented for enums used in frontend/Entity	§3.3
ResVo<T>	Unified response for Controller and inter-service calls	§3.2/§3.11
HttpExchangeClient	Mandatory for inter-service calls	§3.11
keepGlobalFormat=true	Mandatory for @TableField	§3.8
Functional wrapper	Mandatory for MyBatis-Plus wrapper	§3.8
seata TCC	Mandatory for distributed transactions	§3.9
JDK21 + Maven 3.9.10+	Mandatory versions	§3.12
maven wrapper	Must use project wrapper	§3.12
Audit fields	Must exist in business tables	§4
api/inner-api/open-api prefix	Mandatory for Controller paths	§7.1
Param input/Vo output for frontend interfaces	Mandatory for Controller	§7.2
Param input/Dto output for internal interfaces	Mandatory for InnerController	§7.2
Independent Dto/Param for external interfaces	Mandatory for OpenController	§7.2
Add version for concurrent modifications	Must have optimistic lock field in database	§4

Toolchain Quick Reference

Scenario	Tool	Clause
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 Class Layering

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

Layer	Input	Output
repository	Param / Dto	Entity / Dto
service	Param / Dto	Dto / Vo
Frontend Interface Controller	Param	Vo
Internal Interface InnerController	Param	Dto
External Interface OpenController	Param	Dto

Maven Module Structure

<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 Code Layering

- 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
```
→ Frontend interfaces (require gateway authentication)
```
/inner-api
```
→ Internal inter-service calls (no authentication required)
```
/open-api
```
→ External interfaces (require open platform authentication)

Output Constraints

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

Full specification (line number index):
```
references/toc.md
```
Full specification:
```
references/java-coding-spec-v1.md
```

eliteforge-java-coding-spec

NPX Install

Tags

SKILL.md Content (Chinese)