java-development-manual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java开发手册（嵩山版）

Java Development Manual (Songshan Edition)

概述

Overview

本手册基于阿里巴巴Java开发手册（嵩山版），将规约分为7个维度。规约按约束力强弱分为：

级别	含义	说明
【强制】	必须遵守	违反可能导致严重问题
【推荐】	建议遵守	提升代码质量和可维护性
【参考】	可选择性采纳	根据实际情况判断

This manual is based on the Alibaba Java Development Manual (Songshan Edition) and organizes its standards into seven areas. Standards are categorized by the strength of their requirements:

Level	Meaning	Description
Mandatory	Must be followed	Violations may cause serious problems
Recommended	Recommended	Improves code quality and maintainability
Reference	Optionally adopted	Choose based on the actual situation

章节导航

Chapter Navigation

根据需求选择对应章节的详细规约：

章节	适用场景	详细文档
编程规约	命名、格式、OOP、并发、集合处理	coding-convention.md
异常日志	错误码、异常处理、日志规范	exception-log.md
单元测试	测试用例、覆盖率、Mock	unit-test.md
安全规约	SQL注入、XSS、CSRF、脱敏	security.md
MySQL数据库	建表、索引、SQL、ORM	mysql.md
工程结构	分层架构、依赖管理、服务器	project-structure.md
设计规约	UML、设计模式、设计原则	design.md

Select the detailed standards in the corresponding chapter according to your needs:

Chapter	Applicable Scenarios	Detailed Documentation
Coding Conventions	Naming, formatting, OOP, concurrency, collection handling	coding-convention.md
Exceptions and Logging	Error codes, exception handling, logging standards	exception-log.md
Unit Testing	Test cases, coverage, Mock	unit-test.md
Security Standards	SQL injection, XSS, CSRF, data masking	security.md
MySQL Database	Table creation, indexes, SQL, ORM	mysql.md
Project Structure	Layered architecture, dependency management, servers	project-structure.md
Design Conventions	UML, design patterns, design principles	design.md

快速参考

Quick Reference

命名规范速查

Naming Convention Quick Reference

java

// 类名：UpperCamelCase
public class UserService { }
public class UserDO { }      // DO/DTO/VO例外

// 方法名/变量：lowerCamelCase
private String userName;
public void getUserById() { }

// 常量：全大写+下划线
public static final int MAX_RETRY_COUNT = 3;

// 包名：全小写
package com.company.project.service;

java

// 类名：UpperCamelCase
public class UserService { }
public class UserDO { }      // DO/DTO/VO例外

// 方法名/变量：lowerCamelCase
private String userName;
public void getUserById() { }

// 常量：全大写+下划线
public static final int MAX_RETRY_COUNT = 3;

// 包名：全小写
package com.company.project.service;

禁止事项速查

Prohibited Practices Quick Reference

禁止	原因
拼音命名	可读性差
魔法值	难以维护
`SELECT *`	性能和可维护性
Executors创建线程池	可能OOM
字符串拼接SQL	注入风险
finally中return	丢失try返回值
foreach中remove	ConcurrentModificationException

Prohibited	Reason
Pinyin-based naming	Poor readability
Magic values	Difficult to maintain
`SELECT *`	Performance and maintainability issues
Creating thread pools with Executors	May cause OOM
String concatenation for SQL	Injection risk
return in finally	Loses the try return value
remove within foreach	ConcurrentModificationException

必须事项速查

Required Practices Quick Reference

必须	原因
覆写方法加@Override	避免签名错误
表必备三字段	id, create_time, update_time
敏感数据脱敏	隐私保护
参数校验	安全防护
ThreadLocal回收	避免内存泄漏
日志用占位符	性能优化

Required	Reason
Add `@Override` when overriding methods	Prevents signature errors
Required table fields	id, create_time, update_time
Mask sensitive data	Privacy protection
Validate parameters	Security protection
Clean up ThreadLocal	Prevents memory leaks
Use placeholders in log messages	Performance optimization

异常处理速查

Exception Handling Quick Reference

java

// 正确的异常处理
try {
    // 业务逻辑
} catch (SpecificException e) {
    logger.error("操作失败, 参数: {}", params, e);
    throw new BusinessException("用户友好提示", e);
} finally {
    // 资源关闭（JDK7+ try-with-resources）
}

java

// 正确的异常处理
try {
    // 业务逻辑
} catch (SpecificException e) {
    logger.error("操作失败, 参数: {}", params, e);
    throw new BusinessException("用户友好提示", e);
} finally {
    // 资源关闭（JDK7+ try-with-resources）
}

数据库速查

Database Quick Reference

sql

-- 建表必备
CREATE TABLE example (
    `id` bigint unsigned NOT NULL AUTO_INCREMENT,
    `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 索引命名
-- 主键: pk_字段名
-- 唯一: uk_字段名
-- 普通: idx_字段名

sql

-- 建表必备
CREATE TABLE example (
    `id` bigint unsigned NOT NULL AUTO_INCREMENT,
    `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 索引命名
-- 主键: pk_字段名
-- 唯一: uk_字段名
-- 普通: idx_字段名

并发处理速查

Concurrency Handling Quick Reference

java

// 线程池创建
ThreadPoolExecutor executor = new ThreadPoolExecutor(
    corePoolSize,
    maximumPoolSize,
    keepAliveTime,
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(queueCapacity),
    new ThreadFactory() {
        private AtomicInteger counter = new AtomicInteger(1);
        public Thread newThread(Runnable r) {
            return new Thread(r, "worker-" + counter.getAndIncrement());
        }
    },
    new ThreadPoolExecutor.CallerRunsPolicy()
);

// ThreadLocal使用
try {
    threadLocal.set(value);
    // 业务逻辑
} finally {
    threadLocal.remove();  // 必须回收
}

java

// 线程池创建
ThreadPoolExecutor executor = new ThreadPoolExecutor(
    corePoolSize,
    maximumPoolSize,
    keepAliveTime,
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(queueCapacity),
    new ThreadFactory() {
        private AtomicInteger counter = new AtomicInteger(1);
        public Thread newThread(Runnable r) {
            return new Thread(r, "worker-" + counter.getAndIncrement());
        }
    },
    new ThreadPoolExecutor.CallerRunsPolicy()
);

// ThreadLocal使用
try {
    threadLocal.set(value);
    // 业务逻辑
} finally {
    threadLocal.remove();  // 必须回收
}

使用指南

Usage Guide

代码审查场景

Code Review Scenarios

命名检查 → 查看 coding-convention.md 的"命名风格"章节
并发问题 → 查看 coding-convention.md 的"并发处理"章节
异常处理 → 查看 exception-log.md
安全问题 → 查看 security.md

Naming checks → Check the "Naming Style" section of coding-convention.md
Concurrency issues → Check the "Concurrency Handling" section of coding-convention.md
Exception handling → Check exception-log.md
Security issues → Check security.md

新项目搭建场景

New Project Setup Scenarios

架构设计 → 查看 design.md
分层结构 → 查看 project-structure.md
数据库设计 → 查看 mysql.md
单元测试 → 查看 unit-test.md

Architecture design → Check design.md
Layered structure → Check project-structure.md
Database design → Check mysql.md
Unit testing → Check unit-test.md

问题排查场景

Troubleshooting Scenarios

NPE问题 → 查看 exception-log.md 的"NPE防护"
性能问题 → 查看 mysql.md 的"索引规约"
并发问题 → 查看 coding-convention.md 的"并发处理"

NPE issues → Check the "NPE Protection" section of exception-log.md
Performance issues → Check the "Index Standards" section of mysql.md
Concurrency issues → Check the "Concurrency Handling" section of coding-convention.md