java-coding-standards

Java Coding Standards

Treat this skill as a concise work card for Java 17+ / Spring Boot projects.SKILL.md Keep only the process and routing; load specific rules on demand references/ from the reference files under it.

Usage Principles

• In-repository rules take precedence over this skill. If AGENTS.md、CLAUDE.md, local formatting configuration, or adjacent code conflicts with this skill, follow the repository conventions first; only when the conflict affects the result should you explicitly point it out.
• Do not perform large-scale refactoring of unrelated code just to satisfy this skill. Stay close to existing patterns unless the current implementation already poses real correctness, security, transaction, or maintainability risks.
• Rules should be as specific and checkable as possible. When maintaining this skill, always ask one question: after deleting this rule, would the AI be more likely to make real mistakes?
• Prohibitions should be paired with recommended alternatives. For example: do not use field injection; prefer constructor injection, usually with Lombok @RequiredArgsConstructor。
• Mechanical rules should be delegated to tools as much as possible. Prefer relying on formatters, Checkstyle, Spotless, tests, CI, or hooks, rather than constraining formatting only through natural language.

Workflow

When writing or refactoring code

1. First look at the project context: build files, local documentation files, formatter/lint configuration, package structure, and the existing style of similar classes.
2. Load only the reference files truly needed for the current change, selecting them according to the "Reference Routing" below.
3. Control the scope of changes; modify only behavior-related parts as much as possible, and do not do unrelated cleanup along the way.
4. Put logic in the correct layer: Controller handles routing, authentication boundaries, validation annotations, and response conversion; Service handles business orchestration; Manager handles transactions and DAO composition; DAO/Mapper handles persistence.
5. Verify with the smallest but effective commands: prefer running targeted tests, module compilation, formatter, or static checks; if not run, explain why.

When reviewing code

1. Look at bugs and risks first; do not focus on style details first.
2. Sort issues by severity, and provide file/line references as much as possible.
3. For each issue, explain: what rule was violated, why it matters, and how it is recommended to fix it.
4. Raise style issues only when they create maintenance costs or conflict with the repository toolchain.
5. If no issues are found, state that clearly, and also note the remaining testing or verification gaps.

When answering standards-related questions

Prefer answering in this structure: rule, reason, example, and whether there are local overriding conventions in the repository.

Reference Routing

Requirement	Load File
Java formatting, imports, braces, indentation, line breaks, switch, annotations, modifiers, Javadoc, naming	references/google-style.md
Project structure, JavaBean suffixes, Optional, Stream, generics, immutability, modern Java features	references/code-style.md
Modular directory structure, Controller/Service/Manager/DAO layering, URL conventions,@Transactional, design patterns, unified response	references/architecture.md
Exceptions, logging, performance, thread pools, remote calls, security, testing, database design	references/best-practices.md

Core Default Rules

• Format: 2-space indentation, no tabs, 100-column limit, K&R brace style, no wildcard imports, standardized modifier order, add Javadoc for visible APIs when necessary.
• Naming: use UpperCamelCasefor classes, lowerCamelCasefor methods/fields, UPPER_SNAKE_CASEfor constants, package names all lowercase without underscores, project names all lowercase with hyphens.
• API boundaries: do not directly expose Entity. Use Formfor requests, VOfor responses, DTOfor cross-layer transport, BO。BO for internal business objects should not appear in Controller APIs.
• Boolean fields: prefer xxxFlag / xxx_flag, avoid isXxx fields, to avoid serialization and RPC mapping ambiguity.
• Parameter count: try to keep a single method's parameters to no more than 5; when exceeded, prefer encapsulating into a request object or value object.
• URL style: by default follow the repository's existing conventions. If the repository has no clear convention, this skill defaults to preferring non-RESTful GET/POST /module/submodule/action, and placing route annotations on methods for easier searching.
• Documentation annotations: follow the Swagger/OpenAPI system currently used by the repository. If the project uses Swagger @ApiOperation, follow the existing author convention; if the project uses springdoc, follow the local @Operation style.

Default layering rules

• Controller: do not write business logic, do not do data assembly, do not directly access DB/cache/MQ. Only at the request boundary layer, and when the project uses request thread context, obtain the current user here.
• Service: responsible for business orchestration and validation; split large Services by use case.
• Manager: by default place @Transactional(rollbackFor = Exception.class) here, responsible for DAO composition and encapsulating third-party platform details, and minimize the transaction scope as much as possible.
• DAO/Mapper: only do persistence. For MyBatis-Plus projects that adopt this convention, prefer XML mapper SQL, avoid the Wrapper query builder, pass constants in as parameters, and do not write business logic into XML.

Things not to do when there is no local override

• Do not call external HTTP, LLM, S3, MQ, email, or other slow remote interfaces inside a database transaction. Prepare data before the transaction, and if necessary trigger side effects after commit.
• Do not rely on same-class internal calls to trigger @Transactional; instead move the transactional method to another Spring Bean, usually a Manager, or use the repository's existing proxy approach.
• Do not create static exception instances, otherwise the stack trace information will be distorted.
• Do not write empty catch (Exception e) {}; either handle it, wrap it with context, or clearly explain why it can be ignored.
• Do not both log and continue throwing the same exception at the same layer, unless that layer is the final handling layer.
• Do not hide N+1 database calls or remote calls inside Streams or loops; query in batches first, then assemble in memory.
• Do not hardcode secrets, tokens, or vendor base URLs; use configuration and the repository's existing URL validation/client factory.
• Do not use Executors.newFixedThreadPool() or newCachedThreadPool()in production paths; explicitly create ThreadPoolExecutor Bean。

Review checklist

Architecture and API:

• Whether the responsibilities of Controller / Service / Manager / DAO are clearly separated.
• Whether the request/response boundary uses Form / VO / DTO and unified response wrapping.
• Whether local URL and Swagger/OpenAPI conventions are followed.

Transactions and persistence:

• Whether methods that require transactions correctly use rollbackFor = Exception.class。
• Whether remote calls, large loops, or slow operations are mixed into transactions.
• Whether DAO/Mapper maintains persistence responsibilities, with no N+1 access occurring.

Data models and Java style:

• Whether the JavaBean suffix and boolean flag rules are correct.
• Whether methods are short enough and readable, and whether the number of parameters is kept within 5.
• Whether Optional, Stream, record, and switch expression are used only when they improve readability.

Exceptions, logging, and security:

• Whether domain exceptions contain enough context and are not static instances.
• Whether logs use SLF4J, preserve stack traces, avoid duplicate logging, and mask sensitive data.
• Whether external URLs, keys, and user input go through local security utilities or constraints.

Testing and verification:

• Whether key branches, boundaries, and exception paths have focused test coverage.
• Whether the minimal but meaningful compile/test/lint commands were run; if not, whether the reason is explained.

Skill maintenance rules

When maintaining this skill, follow the same principles as excellent CLAUDE.md / AGENTS.md :

• Let SKILL.md only take on routing and execution-layer roles; put long examples and detailed rules into references/。
• Only solidify a rule when it remains valid long-term, is general enough, and truly reduces repeated errors.
• Delete vague rules, such as "write clean code", unless they contain clear checkpoints or alternatives.
• If a rule could be enforced by a formatter, linter, hook, test, or CI, prefer recording the tool and verification commands instead of only writing textual explanations.
• After making major changes to the skill, use the verification process of skill-creator to check it again.