Alibaba Java Development Manual (Huangshan Edition)

Code efficiently, code with quality. This Skill only describes which convention is needed in which situation and the corresponding reference document; the full convention text, including explanations, positive examples, and negative examples, is available in each file in the
references/
directory.

When to Activate This Skill

When writing or reviewing Java code, including naming, formatting, OOP, collections, concurrency, control statements, and comments
When handling exceptions, logs, and error codes
When writing unit tests or evaluating test coverage
When conducting security audits, permission checks, or sensitive data masking
When designing MySQL schemas and indexes, writing SQL, or using an ORM
When planning application layers, second-party library dependencies, or server configurations
When conducting system design or selecting use case, state, sequence, class, or activity diagrams
When defining project coding standards, team development standards, or conducting a Code Review

Convention Levels

Level	Indicator	Meaning
Mandatory	【Mandatory】	Must be followed; violations may cause failures or serious problems
Recommended	【Recommended】	Recommended to improve quality and maintainability
Reference	【Reference】	Optional; apply flexibly according to the actual situation

Scenario Quick Reference: Which Convention to Consult

Locate the conventions that should be followed and their corresponding reference documents according to the scenario. When reviewing or writing code, compare against the table below; whenever an item applies, consult the corresponding
references/
file for positive and negative examples.

1. Naming

Scenario	Convention Summary	Reference Document
Naming a class/interface	UpperCamelCase; DO/PO/DTO/BO/VO/UID are exceptions	01 § Naming Style
Naming a method/variable/parameter	lowerCamelCase	01 § Naming Style
Naming a constant	Uppercase letters plus underscores; keep the meaning complete even if the name is long, such as MAX_STOCK_COUNT	01 § Naming Style
Whether underscores/dollar signs may appear at the beginning or end	Prohibited	01 § Naming Style
Whether Pinyin may be mixed with English or Chinese may be used alone	Prohibited; internationally recognized names such as taobao/hangzhou may be treated as English	01 § Naming Style
Whether discriminatory terms may be used	Prohibited, such as blackList→blockList and slave→secondary	01 § Naming Style
Whether Boolean variables should have an is prefix	Prohibited in POJOs to prevent framework serialization errors	01 § Naming Style
Naming abstract classes, exception classes, and test classes	Abstract classes start with Abstract/Base; exception classes end with Exception; test classes end with Test	01 § Naming Style
Array declaration style	`int[] arrayDemo` , with the type immediately adjacent to the brackets	01 § Naming Style
Package naming conventions	Lowercase, dot-separated, singular words	01 § Naming Style
Naming Service/DAO interfaces and implementations	Use the Impl suffix for implementation classes to distinguish them from interfaces	01 § Naming Style
Naming enum classes and members	Class names end with Enum; member names use uppercase letters and underscores	01 § Naming Style
Method naming at each layer	Use the get/list/count/save·insert/remove·delete/update prefixes	01 § Naming Style
Domain model naming	Use xxxDO/xxxDTO/xxxVO; xxxPOJO is prohibited	01 § Naming Style

2. Constants

Scenario	Convention Summary	Reference Document
An undefined literal appears in code	Magic values are prohibited; constants must be predefined	01 § Constant Definitions
long assignment suffix	Use uppercase L; lowercase l is prohibited	01 § Constant Definitions
Floating-point suffix	Use uppercase D/F consistently	01 § Constant Definitions
Organizing constant classes	Maintain separate classes by function; a single catch-all constant class is prohibited	01 § Constant Definitions
Variables with a fixed value range	Prefer an enum	01 § Constant Definitions

3. Code Formatting

Scenario	Convention Summary	Reference Document
Braces/indentation/spaces/line breaks	For non-empty blocks, do not insert a line break before the opening brace and insert one after it; use four spaces for indentation; Tab is prohibited	01 § Code Formatting
Spaces around operators and keywords	Add spaces on both sides of binary and ternary operators; add a space between if/for/while and its parentheses	01 § Code Formatting
Single-line length	Must not exceed 120 characters; wrap long lines according to the rules	01 § Code Formatting
Method length	A method must not exceed 80 lines	01 § Code Formatting
File encoding/line endings	UTF-8; Unix line endings	01 § Code Formatting
After commas in method parameters	A space is required	01 § Code Formatting

4. OOP

Scenario	Convention Summary	Reference Document
Overriding a parent class method	@Override is required	01 § OOP Conventions
Calling equals	Call equals on constants or objects guaranteed to have a value; Objects#equals is recommended	01 § OOP Conventions
Comparing wrapper integer types	Use equals instead of ==	01 § OOP Conventions
Testing floating-point equality	Both == and equals are prohibited; use a tolerance range or BigDecimal	01 § OOP Conventions
Comparing BigDecimal values	Use compareTo instead of equals	01 § OOP Conventions
Constructing BigDecimal	BigDecimal(double) is prohibited; use a String constructor or valueOf	01 § OOP Conventions
DO property type and field type	Must match, such as bigint→Long	01 § OOP Conventions
Primitive versus wrapper types for POJOs and local variables	POJOs and RPC parameters must use wrapper types; primitive types are recommended for local variables	01 § OOP Conventions
POJO default values/toString/serialVersionUID	Do not set default values; toString is required; do not change serialVersionUID when adding properties	01 § OOP Conventions
Whether a POJO may contain both isXxx and getXxx	They must not coexist	01 § OOP Conventions
Business logic in constructors	Prohibited; use an init method instead	01 § OOP Conventions
String concatenation inside a loop	Use StringBuilder.append	01 § OOP Conventions
Strict access control	Utility classes require a private constructor; members should have the minimum possible visibility	01 § OOP Conventions

5. Date and Time

Scenario	Convention Summary	Reference Document
Year in date formatting	Use lowercase y; YYYY is prohibited because it may cross year boundaries	01 § Date and Time
Case for month/minute/hour	Month=M, minute=m, 24-hour=H, 12-hour=h	01 § Date and Time
Obtaining milliseconds	Use System.currentTimeMillis(); new Date().getTime() is prohibited	01 § Date and Time
java.sql.Date/Time/Timestamp	Prohibited	01 § Date and Time
Hard-coding 365 days per year	Prohibited; use LocalDate.lengthOfYear()	01 § Date and Time

6. Collections

Scenario	Convention Summary	Reference Document
Overriding equals without overriding hashCode	hashCode must also be overridden	01 § Collection Handling
Checking whether a collection is empty	Use isEmpty(); size()==0 is prohibited	01 § Collection Handling
Stream toMap with duplicate keys	A mergeFunction must be provided	01 § Collection Handling
Stream toMap with a null value	It throws an NPE; guard against this case	01 § Collection Handling
Casting subList to ArrayList	Prohibited	01 § Collection Handling
Converting a collection to an array	Use toArray(new T[0])	01 § Collection Handling
Modifying the result of Arrays.asList	add/remove/clear are prohibited	01 § Collection Handling
Calling remove/add inside foreach	Prohibited; use an Iterator	01 § Collection Handling
Initial capacity of a collection	Specify an initial size, such as the default HashMap size of 16	01 § Collection Handling
Iterating over a Map	Use entrySet or forEach	01 § Collection Handling
Storing null in ConcurrentHashMap	Prohibited because it throws an NPE	01 § Collection Handling

7. Concurrency

Scenario	Convention Summary	Reference Document
Thread safety of singletons	Must be guaranteed	01 § Concurrency Handling
Naming newly created threads	Specify a meaningful thread name	01 § Concurrency Handling
Explicitly creating a Thread with new Thread	Prohibited; use a thread pool	01 § Concurrency Handling
Creating a thread pool	Use ThreadPoolExecutor; Executors is prohibited because of OOM risks	01 § Concurrency Handling
Thread safety of SimpleDateFormat	It is not thread-safe; do not define it as static without locking; use DateTimeFormatter on JDK8	01 § Concurrency Handling
Cleaning up ThreadLocal	In thread-pool scenarios, remove it in a try-finally block	01 § Concurrency Handling
Lock performance	Prefer lock-free approaches; keep lock blocks as small as possible; prefer object locks over class locks	01 § Concurrency Handling
Lock ordering for multiple resources	The order must be consistent to prevent deadlocks	01 § Concurrency Handling
Position of lock relative to try	Place the lock outside the try block	01 § Concurrency Handling
Before releasing a tryLock	Check whether the lock is still held	01 § Concurrency Handling
Preventing lost updates during concurrent updates	Use locking or optimistic locking with a version	01 § Concurrency Handling
Locking strategy for financially sensitive information	Use pessimistic locking	01 § Concurrency Handling
Random numbers in multiple threads	Use ThreadLocalRandom	01 § Concurrency Handling
Double-checked locking	The target property must be volatile	01 § Concurrency Handling

8. Control Statements

Scenario	Convention Summary	Reference Document
switch without break/default	Each branch must terminate or include an explanatory comment; default is required	01 § Control Statements
switch argument is a null String	Check for null first	01 § Control Statements
Braces for if/else/for/while	Braces are required	01 § Control Statements
NPE caused by a ternary operator	Watch for automatic unboxing	01 § Control Statements
Equality-based termination under high concurrency	Prohibited; use range comparison	01 § Control Statements
if-else nesting depth	Must not exceed three levels; use guard clauses, the Strategy pattern, or the State pattern	01 § Control Statements
Input protection for batch APIs	Required	01 § Control Statements
Timing of parameter validation	Low-frequency, high-cost, high-availability, open-interface, and sensitive entry-point parameters must be validated	01 § Control Statements

9. Comments

Scenario	Convention Summary	Reference Document
Class/field/method comments	Use Javadoc `/** */` ; `//` is prohibited	01 § Comment Conventions
Abstract method comments	Must explain what the method does and what implementations are required to do	01 § Comment Conventions
Creator and creation date	Required for every class	01 § Comment Conventions
Enum field comments	Required	01 § Comment Conventions
TODO/FIXME	Include the marker owner, time, and expected resolution time	01 § Comment Conventions
Commented-out code	Explain the reason above it or delete it	01 § Comment Conventions

10. Frontend and Backend

Scenario	Convention Summary	Reference Document
API protocol/path/method	Use HTTPS in production; path nouns should be plural, lowercase, and underscore-separated; suffixes are prohibited	01 § Frontend and Backend Conventions
Empty response from a list API	Return an empty array/object such as []/{}; null is prohibited	01 § Frontend and Backend Conventions
Error response body	Include the HTTP status code, errorCode, errorMessage, and a user-facing message	01 § Frontend and Backend Conventions
JSON key naming	lowerCamelCase	01 § Frontend and Backend Conventions
Returning very large integers to the frontend	Use String; Long is prohibited because it may lose precision	01 § Frontend and Backend Conventions
URL parameter length	Must not exceed 2048 bytes	01 § Frontend and Backend Conventions
Time format	yyyy-MM-dd HH:mm:ss, GMT	01 § Frontend and Backend Conventions
Pagination out of bounds	If the frontend value is less than 1, return the first page; if the backend value exceeds the total number of pages, return the last page	01 § Frontend and Backend Conventions

11. Exceptions

Scenario	Convention Summary	Reference Document
Pre-checkable RuntimeException	Prevent it in advance; catching it, such as catching NPE, is prohibited	02 § Exception Handling
Using exceptions for flow control	Prohibited	02 § Exception Handling
Catching an exception without handling it	Discarding it is prohibited; handle it or rethrow it	02 § Exception Handling
Rolling back after catching an exception in a transaction	A manual rollback is required	02 § Exception Handling
Closing resources in finally	Required; use try-with-resources on JDK7	02 § Exception Handling
Returning from finally	Prohibited	02 § Exception Handling
RPC/second-party package/dynamic class exceptions	Catch Throwable, such as NoSuchMethodError	02 § Exception Handling
NPE prevention scenarios	Unboxing, database results, collection elements, remote calls, Session access, and chained calls	02 § Exception Handling
Custom exceptions	Must have business meaning; directly throwing RuntimeException/Exception/Throwable is prohibited	02 § Exception Handling
Cross-application RPC return value	Prefer Result+isSuccess()	02 § Exception Handling

12. Logging

Scenario	Convention Summary	Reference Document
Selecting a logging API	Use the SLF4J facade; calling Log4j/Logback directly is prohibited	02 § Logging Conventions
Log retention period	At least 15 days; at least six months for sensitive operations	02 § Logging Conventions
String concatenation	Use the `{}` placeholder	02 § Logging Conventions
Before outputting trace/debug/info logs	A log-level switch check is required	02 § Logging Conventions
Duplicate logging	Set additivity=false	02 § Logging Conventions
System.out/printStackTrace	Prohibited in production environments	02 § Logging Conventions
Exception log content	Include the incident context and stack trace	02 § Logging Conventions
Objects written to logs	Do not convert them to strings with a JSON tool; use toString	02 § Logging Conventions
Sensitive information in logs	Mask the data	02 § Logging Conventions

13. Error Codes

Scenario	Convention Summary	Reference Document
Error code format	A five-character string consisting of a source letter A/B/C and four digits	02 § Error Codes
Completely successful result	Return 00000	02 § Error Codes
Whether an error code includes a version or level	It must not	02 § Error Codes
Returning an error code directly to the user	Prohibited	02 § Error Codes
Translating a third-party error code	Convert C to B and retain the original error code	02 § Error Codes
Complete error code list	175 entries	08 § Error Code List

14. Unit Testing

Scenario	Convention Summary	Reference Document
Basic testing principles	AIR: Automated, Independent, Repeatable	03 Unit Testing
Test verification method	Use assertions; manual verification with System.out is prohibited	03 Unit Testing
Test independence	Test cases must not call one another or depend on execution order	03 Unit Testing
Test granularity	Generally class-level, with method-level tests where appropriate	03 Unit Testing
Test directory	src/test/java	03 Unit Testing
Coverage target	70% statement coverage; 100% statement and branch coverage for core modules	03 Unit Testing
Test case design	BCDE: Boundary, Correct, Design, Error	03 Unit Testing
DB-related tests	Prepare data in the program, roll back automatically, and use prefix/suffix identifiers	03 Unit Testing

15. Security

Scenario	Convention Summary	Reference Document
User page/function permissions	Validation is required to prevent horizontal privilege escalation	04 Security Conventions
Displaying sensitive data	Masking is required, such as 139****1219 for a phone number	04 Security Conventions
SQL parameters	Use parameter binding; string concatenation is prohibited to prevent injection	04 Security Conventions
Request parameter validation	Validate parameters for validity to prevent OOM, slow queries, SSRF, and injection	04 Security Conventions
Rendering user data in HTML	Filter and escape it to prevent XSS	04 Security Conventions
Form/AJAX submission	CSRF validation is required	04 Security Conventions
External URL redirection	Apply whitelist filtering	04 Security Conventions
Platform resources such as SMS, email, and payments	Prevent replay attacks through quantity/frequency limits and verification codes	04 Security Conventions
File uploads	Validate the file size and type	04 Security Conventions
Passwords in configuration files	Encryption is required	04 Security Conventions

16. Table Design

Scenario	Convention Summary	Reference Document
Boolean field naming	is_xxx with unsigned tinyint	05 § Table Design Conventions
Table/field names	Use lowercase letters or numbers; uppercase letters, leading numbers, and numbers between two underscores are prohibited	05 § Table Design Conventions
Plural table names	Prohibited	05 § Table Design Conventions
Reserved words	Prohibited, such as desc/range/match	05 § Table Design Conventions
Index naming	pk_/uk_/idx_	05 § Table Design Conventions
Decimal type	Use decimal; float/double are prohibited	05 § Table Design Conventions
varchar length	Must not exceed 5000; use text in a separate table if it exceeds the limit	05 § Table Design Conventions
Required fields	id/create_time/update_time	05 § Table Design Conventions
Physical deletion	Prohibited; use logical deletion	05 § Table Design Conventions
When to partition databases or tables	A single table exceeds five million rows or 2 GB	05 § Table Design Conventions

17. Indexes

Scenario	Convention Summary	Reference Document
Unique business field	A unique index is required, including for composite fields	05 § Index Conventions
Number of tables in a join	Must not exceed three	05 § Index Conventions
varchar index	The index length must be specified	05 § Index Conventions
Left-fuzzy or fully fuzzy queries	Prohibited; use a search engine	05 § Index Conventions
Using an index for order by	Place the sorting field last in a composite index	05 § Index Conventions
Covering index	Use it to avoid table lookups	05 § Index Conventions
Composite index field order	Place the column with the highest cardinality leftmost; place equality-condition columns first	05 § Index Conventions

18. SQL Statements

Scenario	Convention Summary	Reference Document
Counting rows	Use count(*); count(column)/count(constant) is prohibited	05 § SQL Statements
Checking for NULL	Use ISNULL()	05 § SQL Statements
NPE from sum()	Use IFNULL(SUM(col),0)	05 § SQL Statements
Pagination count is zero	Return immediately	05 § SQL Statements
Foreign keys and cascades	Prohibited; handle them in the application layer	05 § SQL Statements
Stored procedures	Prohibited	05 § SQL Statements
Correcting data	Run select to verify the records before update/delete	05 § SQL Statements
Column names from multiple tables	Qualify them with table aliases	05 § SQL Statements
Size of an IN collection	Keep it within 1,000 items	05 § SQL Statements

19. ORM Mapping

Scenario	Convention Summary	Reference Document
Query fields	select * is prohibited; list the fields explicitly	05 § ORM Mapping
resultMap	Must be defined; resultClass is prohibited; map is_ to xxx for Boolean fields	05 § ORM Mapping
Parameter placeholders	Use #{}; ${} is prohibited because of injection risks	05 § ORM Mapping
queryForList(start,size)	Not recommended because of OOM risks	05 § ORM Mapping
Result set container	Directly receiving results in HashMap/Hashtable is prohibited	05 § ORM Mapping
Updating records	update_time must be updated at the same time	05 § ORM Mapping
Update interface that modifies every field	Prohibited; update only the fields that changed	05 § ORM Mapping

20. Application Layering

Scenario	Convention Summary	Reference Document
Layered structure	Open API/Terminal Display/Web/Service/Manager/DAO	06 § Application Layering
Exception handling by layer	DAO does not log; Service writes logs; Web does not rethrow or jump directly to an error page; Open API returns an error code	06 § Application Layering
Domain models	Responsibilities of DO/DTO/BO/Query/VO at each layer	06 § Application Layering
Query parameter encapsulation	Use a Query object for more than two parameters; Map is prohibited	06 § Application Layering

21. Second-Party Library Dependencies

Scenario	Convention Summary	Reference Document
GAV naming	GroupId may contain at most four levels; ArtifactId uses product-line-module-name	06 § Second-Party Library Dependencies
Version number	Use major.minor.patch and start with 1.0.0	06 § Second-Party Library Dependencies
SNAPSHOT dependency in production	Prohibited	06 § Second-Party Library Dependencies
Same GAV with different versions	Prohibited	06 § Second-Party Library Dependencies
Unified version variables	Define unified version variables in the dependency group	06 § Second-Party Library Dependencies
pom dependency management	Put dependencies in dependencies and perform version arbitration in dependencyManagement	06 § Second-Party Library Dependencies
Using an enum as an interface return value	Prohibited	06 § Second-Party Library Dependencies

22. Servers

Scenario	Convention Summary	Reference Document
Remote call timeout	Must be configured	06 § Servers
High-concurrency time_wait	Reduce tcp_fin_timeout	06 § Servers
File descriptor count	Increase fd	06 § Servers
OOM dump	-XX:+HeapDumpOnOutOfMemoryError	06 § Servers
Xms/Xmx	Set them to the same value in production environments	06 § Servers

23. System Design

Scenario	Convention Summary	Reference Document
Storage solution/data structure design	Review and approval are required, followed by documentation	07 Design Conventions
Selecting a use case diagram	User>1 and UseCase>5	07 Design Conventions
Selecting a state diagram	Business object states>3	07 Design Conventions
Selecting a sequence diagram	Objects involved in the call chain>3	07 Design Conventions
Selecting a class diagram	Model classes>5 with complex dependencies	07 Design Conventions
Selecting an activity diagram	More than two collaborating objects with a complex process	07 Design Conventions
Identifying weak dependencies	A degradation strategy and contingency plan must be designed	07 Design Conventions
Design principles	Single responsibility, composition over inheritance, dependency inversion, open/closed principle, and DRY	07 Design Conventions
Agile development misconception	Agile is not equivalent to telling stories, writing code, and releasing	07 Design Conventions
Accessibility design	Tab focus, multiple CAPTCHA methods, and custom control interactions	07 Design Conventions

Anti-Pattern Red Lines (Stop Immediately When Found)

Anti-Pattern	Violated Convention	Reference
Variable names mix Pinyin with English or use Chinese	Naming	01 § Naming Style
Magic values appear in code	Constants	01 § Constant Definitions
Tab indentation or a line longer than 120 characters	Formatting	01 § Code Formatting
`param.equals("test")`	OOP	01 § OOP Conventions
Comparing an Integer with ==	OOP	01 § OOP Conventions
`new BigDecimal(0.1)`	OOP	01 § OOP Conventions
Adding an is prefix to a POJO Boolean field	OOP	01 § OOP Conventions
`new Date().getTime()`	Date and time	01 § Date and Time
Calling remove/add inside foreach	Collections	01 § Collection Handling
Creating a thread pool with Executors.newXxx	Concurrency	01 § Concurrency Handling
Defining SimpleDateFormat as static without locking	Concurrency	01 § Concurrency Handling
Returning from finally	Exceptions	02 § Exception Handling
Catching NPE instead of checking in advance	Exceptions	02 § Exception Handling
Calling the Log4j API directly	Logging	02 § Logging Conventions
Using System.out/printStackTrace in production	Logging	02 § Logging Conventions
Concatenating SQL parameters as strings	Security	04 Security Conventions
Using a select * query	ORM	05 § ORM Mapping
Passing parameters with ${}	ORM	05 § ORM Mapping
Physical deletion	Table design	05 § Table Design Conventions
Using foreign keys, cascades, or stored procedures	SQL	05 § SQL Statements
Using a SNAPSHOT dependency in production	Dependencies	06 § Second-Party Library Dependencies

Reference Document Index

The full convention text, including explanations, positive examples, negative examples, and complete entries, is stored in the

references/

directory:

File	Content	Subchapters
01-coding-conventions.md	I. Programming Conventions	Naming Style/Constant Definitions/Code Formatting/OOP Conventions/Date and Time/Collection Handling/Concurrency Handling/Control Statements/Comment Conventions/Frontend and Backend Conventions/Other
02-exception-logging.md	II. Exceptions and Logging	Error Codes/Exception Handling/Logging Conventions
03-unit-testing.md	III. Unit Testing	AIR/BCDE/Coverage/Data Preparation
04-security.md	IV. Security Conventions	Permissions/Masking/Injection/XSS/CSRF/Uploads/Encryption
05-mysql-database.md	V. MySQL Databases	Table Design Conventions/Index Conventions/SQL Statements/ORM Mapping
06-engineering-structure.md	VI. Engineering Structure	Application Layering/Second-Party Library Dependencies/Servers
07-design-conventions.md	VII. Design Conventions	Storage Review/Diagram Selection/Design Principles
08-appendix.md	Appendix	Preface/Version History/Glossary of Proper Nouns/Error Code List (175 entries)

Source: Alibaba Group Technical Team · Global Java Community Developers
Version: 1.7.1 Huangshan Edition (2022.02.03)
Vision: Code efficiently, code with quality

alibaba-java-manual

NPX Install

Tags

SKILL.md Content (Chinese)