EP20-《阿里巴巴Java开发手册》读书笔记

第1章　编程规约

本章是传统意义上的代码规范，包括变量命名、代码风格、控制语句、代码注释、前后端规约等基本的编程习惯，以及从高并发场景中提炼出来的集合处理技巧与并发多线程的注意事项。

1.2 常量定义

不要使用一个常量类维护所有的常量，要按常量功能进行归类，分开维护。

1
2

说明：大而全的常量类杂乱无章，必须使用查找功能才能定位到要修改的常量，既不利于理解，也不利于维护。
正例：缓存相关常量放在类CacheConsts下；系统配置相关常量放在类SystemConfigConsts下。

常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量和类内共享常量。

1）跨应用共享常量：放置在二方库中，通常是在client.jar中的constant目录下。
2）应用内共享常量：放置在一方库中，通常是在子模块中的constant目录下。
3）子工程内部共享常量：即在当前子工程的constant目录下。
4）包内共享常量：即在当前包下单独的constant目录下。
5）类内共享常量：直接在类内部以private static final定义。

1.3代码格式

if/for/while/switch/do等保留字与括号之间都必须加空格。
任何二目、三目运算符的左右两边都需要加一个空格。
注释的双斜线与注释内容之间有且仅有一个空格。

1	// 这是一个示例注释，双斜线之后有一个空格

在进行类型强制转换时，右括号与被强制转换的值之间不需要任何空格隔开。

1 2	double first = 3.14d; int second = (int)first + 2;

在定义和传入方法参数时，多个参数逗号后面必须加空格。

1	method(arg1, arg2, arg3);

单个方法的总行数不超过80。

1	代码逻辑分清红花和绿叶、个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。

在不同逻辑、不同语义、不同业务的代码之间插入一个空行，分隔开来以提升可读性。

1.4 OOP规约（object-oriented programming ）

避免通过一个类的对象引用访问此类的静态变量或静态方法，造成编译器解析成本无谓增加，直接用类名访问即可。
对外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。若接口过时，则必须加@Deprecated注解，并清晰地说明采用的新接口或者新服务是什么。
Object的equals方法容易抛空指针异常，应使用常量或确定有值的对象调用equals。
1
2
"test".equals(object);//正例
object.equals("test");//反例
浮点数之间的等值判断，基本数据类型不能用==进行比较，包装数据类型不能用equals方法判断。

说明：浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进制无法精确表示大部分十进制小数，具体原理参考《码出高效：Java开发手册》。
禁止使用构造方法BigDecimal(double)的方式把double值转化为BigDecimal对象。

说明：BigDecimal(double)存在精度损失风险，在精确计算或值比较的场景中，可能会导致业务逻辑出现异常。
在定义DO/DTO/VO等POJO类时，不要设定任何属性默认值。
禁止在POJO类中同时存在对应属性xxx的isXxx()和getXxx()方法。

说明：框架在调用属性xxx的提取方法时，并不能确定哪种方法一定是被优先调用的。
当使用索引访问用String的split方法得到的数组时，需在最后一个分隔符后做有无内容的检查，否则会有抛出IndexOutOfBoundsException的风险。
当一个类有多个构造方法，或者多个同名方法时，这些方法应该按顺序放置在一起，便于阅读。优先于第10条规则。
类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter方法。

说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载的信息价值较低，所有Service和DAO的getter/setter方法都放在类体的最后。
在循环体内，字符串的连接方式使用StringBuilder的append方法扩展。
final可以声明类、成员变量、方法及本地变量，下列情况使用final关键字。

1）不允许被继承的类，如：String类。

2）不允许修改引用的域对象，如：POJO类的域变量。

3）不允许被覆写的方法，如：POJO类的setter方法。

4）不允许在运行过程中给局部变量重新赋值。

5）避免上下文重复使用一个变量，使用final描述可以强制重新定义一个变量，方便更好地重构。
慎用Object的clone方法拷贝对象。

说明：对象的clone方法默认是浅拷贝，若想实现深拷贝，需要覆写clone方法来实现域对象的深度遍历式拷贝。

1.5　日期时间

在日期格式化时，传入pattern中表示年份统一使用小写的y。

说明：在日期格式化时，yyyy表示当天所在的年，大写的YYYY表示week in which year（JDK 7之后引入的概念），意思是当天所在的周属于的年份。一周从周日开始，周六结束，只要本周跨年，返回的YYYY就是下一年。
1
new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
在日期格式中，分清楚大写的M和小写的m、大写的H和小写的h分别代表的意义。

说明：日期格式中的这两对字母表意如下：1）表示月份，用大写的M；2）表示分钟，用小写的m；3）表示24小时制，用大写的H；4）表示12小时制，用小写的h。
不要在程序中写死一年为365天，避免在闰年时出现日期转换错误或程序逻辑错误。
1
2
// 获取今年的天数
int days = LocalDate.now().lengthOfYear();
使用枚举值指代月份。如果使用数字，则注意Date、Calendar等日期相关类的月份（month）取值在0～11之间。

说明：参考JDK原生注释，Month value is 0-based.
1
e.g. 0 for January

1.6　集合处理

判断所有集合内部的元素是否为空，应使用isEmpty()方法，而不是使用size()==0的方式。

说明：在某些集合中，前者的时间复杂度为O(1)，而且可读性更好。
在使用java.util.stream.Collectors类的toMap()方法转为Map集合时，一定要使用含有参数类型为BinaryOperator、参数名为mergeFunction的方法，否则当出现相同key值时，会抛出IllegalStateException异常。

说明：参数mergeFunction的作用是当出现key重复时，自定义对value的处理策略。
在使用java.util.stream.Collectors类的toMap()方法转为Map集合时，一定要注意当value为null时，会抛出NPE异常。
1
2
3
4
会存在如下判断：
if (value == null || remappingFunction == null){
throw new NullPointerException();
}
ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCastException异常，即java.util. RandomAccessSubList cannot be cast to java.util. ArrayList。

说明：subList()返回的是ArrayList的内部类SubList，并不是ArrayList本身，而是ArrayList的一个视图，对于SubList的所有操作最终会反映到原列表上。
Collections类返回的对象，如：emptyList()/ singletonList()等都是immutable list，不可对其添加或者删除元素。
在使用Collection接口任何实现类的addAll()方法时，都要对输入的集合参数进行NPE判断。

说明：ArrayList#addAll方法的第一行代码即Object[] a = c. toArray();，其中，c为输入集合参数，如果为null，则直接抛出异常。
当使用工具类Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear方法会抛出UnsupportedOperationException异常。

说明：asList的返回对象是一个Arrays内部类，并没有实现集合的修改方法。Arrays.asList体现的是适配器模式，只是转换接口，后台的数据仍是数组。

在无泛型限制定义的集合赋值给泛型限制的集合中，当使用集合元素时，需要进行instanceof判断，避免抛出ClassCastException异常。

// 无泛型限制的集合：可以存储任意类型的对象，但取出时需要手动进行类型转换，容易引发ClassCastException
List list = new ArrayList(); 
list.add("Hello");
list.add(123); // 可以存储不同类型
String str = (String) list.get(0); // 需要强制类型转换
Integer num = (Integer) list.get(1); // 需要强制类型转换
// 泛型限制的集合
List<String> genericList = new ArrayList<>();
genericList.add("Hello");
// genericList.add(123); // 编译错误，只能存储String类型
String str = genericList.get(0); // 无需强制类型转换

不要在foreach循环中对元素进行remove/add操作。当进行remove操作时，请使用Iterator方式。如果是并发操作，需要对Iterator对象加锁。

public static void main(String[] args) {
    // 创建一个集合
    List<String> list = new ArrayList<>();
    list.add("Apple");
    list.add("Banana");
    list.add("Cherry");
    // 获取 Iterator 对象
    Iterator<String> iterator = list.iterator();
    // 遍历集合
    while (iterator.hasNext()) {
        String fruit = iterator.next(); // 获取下一个元素
        System.out.println(fruit);
        // 如果需要，可以移除当前元素
        if (fruit.equals("Banana")) {
            iterator.remove(); // 移除 "Banana"
        }
    }
    // 输出修改后的集合
    System.out.println("修改后的集合: " + list);
}

当使用泛型集合定义时，在JDK 7及以上版本中，使用diamond语法或全省略。

说明：菱形泛型即diamond，直接使用<>指代前边已经指定的类型。

使用entrySet遍历Map类集合K/V，而不是用keySet方式遍历。

说明：keySet方式其实遍历了两次，一次是转为Iterator对象，另一次是从hashMap中取出Key所对应的Value。而entrySet只遍历了一次就把Key和Value都放到了entry中，效率更高。如果是JDK 8，则使用Map.forEach方法。

正例：values()返回的是V值集合，是一个list集合对象；keySet()返回的是K值集合，是一个Set集合对象；entrySet()返回的是K-V值组合集合。

import java.util.HashMap;
import java.util.Map;
public class MapTraversalExample {
    public static void main(String[] args) {
        // 创建一个 Map 集合
        Map<String, Integer> map = new HashMap<>();
        map.put("Apple", 10);
        map.put("Banana", 20);
        map.put("Cherry", 30);

        // 1. 使用 keySet 方式遍历（不推荐，效率较低）
        	// (1)通过 map.keySet() 获取所有的 Key，然后遍历 Key。每次遍历时，需要通过 map.get(key) 从 Map 中获取对应的 Value。
        	// (2)缺点：遍历了两次，第一次遍历 Key，第二次通过 Key 获取 Value，效率较低。
        System.out.println("使用 keySet 方式遍历：");
        for (String key : map.keySet()) {
            Integer value = map.get(key); // 需要额外从 Map 中获取 Value
            System.out.println("Key: " + key + ", Value: " + value);
        }

        // 2. 使用 entrySet 方式遍历（推荐，效率更高）
        	//(1)通过 map.entrySet() 获取所有的 Map.Entry 对象。每个 Map.Entry 对象包含一个 Key 和对应的 Value。
        	//(2)优点：只需遍历一次，直接从 Entry 中获取 Key 和 Value，效率更高。
        System.out.println("\n使用 entrySet 方式遍历：");
        for (Map.Entry<String, Integer> entry : map.entrySet()) {
            String key = entry.getKey();
            Integer value = entry.getValue(); // 直接从 Entry 中获取 Key 和 Value
            System.out.println("Key: " + key + ", Value: " + value);
        }

        // 3. 使用 JDK 8 的 forEach 方法（推荐，代码更简洁）
        	//(1)使用 map.forEach((key, value) -> { ... }) 方法，直接遍历 Key 和 Value。
        	//(2)优点：代码更简洁，可读性更高。
        System.out.println("\n使用 JDK 8 的 forEach 方法遍历：");
        map.forEach((key, value) -> {
            System.out.println("Key: " + key + ", Value: " + value);
        });
    }
}

高度注意Map类集合K/V能否存储null值，如表1-1所示。
合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。

说明：有序性指遍历的结果按某种比较规则依次排列。稳定性指集合每次遍历的元素次序是一定的。如：ArrayList是order/unsort；HashMap是unorder/unsort；TreeSet是order/sort。
利用Set元素唯一的特性，可以快速对一个集合进行去重操作，避免使用List的contains()进行遍历、去重或者判断包含操作。

1.7　并发处理

当创建线程或线程池时，请指定有意义的线程名称，出错时方便回溯。

（1）为单个线程指定名称：在创建 Thread 时，通过构造方法的第二个参数指定线程名称。

public class NamedThreadExample {
    public static void main(String[] args) {
        // 创建一个线程，并指定有意义的名称
        Thread thread = new Thread(() -> {
            System.out.println("线程正在执行任务...");
            // 模拟任务执行
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }, "File-Processing-Thread"); // 指定线程名称为 "File-Processing-Thread"

        // 启动线程
        thread.start();

        // 打印线程名称
        System.out.println("线程名称: " + thread.getName());
    }
}

（2）为线程池指定线程名称：使用自定义的 ThreadFactory，在 newThread 方法中为线程指定名称。

import java.util.concurrent.*;

public class NamedThreadPoolExample {
    public static void main(String[] args) {
        // 自定义线程工厂，为线程池中的线程指定有意义的名称
        ThreadFactory threadFactory = new ThreadFactory() {
            private int count = 0;

            @Override
            public Thread newThread(Runnable r) {
                return new Thread(r, "Task-Thread-" + (++count)); // 指定线程名称
            }
        };

        // 创建线程池，使用自定义的线程工厂
        ExecutorService executor = Executors.newFixedThreadPool(3, threadFactory);

        // 提交任务到线程池
        for (int i = 1; i <= 5; i++) {
            int taskId = i;
            executor.submit(() -> {
                System.out.println("任务 " + taskId + " 正在由线程 " + Thread.currentThread().getName() + " 执行");
                // 模拟任务执行
                try {
                    Thread.sleep(1000);
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
            });
        }

        // 关闭线程池
        executor.shutdown();
    }
}

（3）使用 Guava 的 ThreadFactoryBuilder（推荐）：更方便地指定线程名称格式。

import com.google.common.util.concurrent.ThreadFactoryBuilder;
import java.util.concurrent.*;
  
public class GuavaThreadPoolExample {
    public static void main(String[] args) {
        // 使用 Guava 的 ThreadFactoryBuilder 创建线程工厂
        ThreadFactory threadFactory = new ThreadFactoryBuilder()
                .setNameFormat("Guava-Thread-%d") // 指定线程名称格式
                .build();
        // 创建线程池，使用 Guava 的线程工厂
        ExecutorService executor = Executors.newFixedThreadPool(3, threadFactory);
        // 提交任务到线程池
        for (int i = 1; i <= 5; i++) {
            int taskId = i;
            executor.submit(() -> {
                System.out.println("任务 " + taskId + " 正在由线程 " + Thread.currentThread().getName() + " 执行");
                // 模拟任务执行
                try {
                    Thread.sleep(1000);
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
            });
        }
        // 关闭线程池
        executor.shutdown();
    }
}

线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。

说明：使用线程池的好处是减少在创建和销毁线程上消耗的时间及系统资源，解决资源不足的问题。如果不使用线程池，则有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。
SimpleDateFormat是线程不安全的类，一般不要定义为static变量，如果定义为static，则必须加锁，或者使用DateUtils工具类。

说明：如果是JDK 8的应用，可以使用Instant代替Date，LocalDateTime代替Calendar，DateTimeFormatter代替SimpleDateFormat。官方给出的解释：simple beautiful strong immutable thread-safe。
必须回收自定义的ThreadLocal变量，尤其在线程池场景下，线程经常会被复用，如果不清理自定义的ThreadLocal变量，则可能会影响后续业务逻辑和造成内存泄露等问题。尽量在代理中使用try-finally块回收。
1
2
3
4
5
6
objectThreadLocal.set(userInfo);
try{
//代码省略
}finally{
objectThreadLocal.remove();
}
在高并发场景中，同步调用应该考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。

说明：使加锁的代码块工作量尽可能的小，避免在锁代码块中调用RPC方法。

RPC（Remote Procedure Call，远程过程调用） 是一种允许程序调用远程服务器上的方法或函数的机制，就像调用本地方法一样。RPC 的核心思想是隐藏网络通信的复杂性，使开发者能够像调用本地方法一样调用远程服务。
在对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。

说明：如果线程一需要对表A、B、C依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是A、B、C，否则可能出现死锁。
在使用阻塞等待获取锁的方式中，必须在try代码块之外，并且在加锁方法与try代码块之间没有任何可能抛出异常的方法调用，避免加锁成功后，在finally中无法解锁。

说明一：如果在lock方法与try代码块之间的方法调用抛出异常，那么无法解锁，造成其他线程无法成功获取锁。

说明二：如果lock方法在try代码块之内，可能由于其他方法抛出异常，导致在finally代码块中，unlock对未加锁的对象尝试解锁，它会调用AQS的try Release方法（取决于具体实现类），抛出Illegal MonitorStateException异常。

说明三：在Lock对象的lock方法实现中，可能抛出unchecked异常，产生的后果与说明二相同。
1
2
3
4
5
6
7
8
Lock lock = new XxxLock();
lock.lock();
try {
doSomething();
doOthers();
} finally {
lock.unlock();
}
在并发修改同一记录时，为避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存层加锁，要么在数据库层使用乐观锁，使用version作为更新依据。

说明：如果每次访问冲突概率小于20%，则推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于3次。

与资金相关的金融敏感信息，使用悲观锁策略。

说明：乐观锁在获得锁的同时已经完成了更新操作，校验逻辑容易出现漏洞。另外，乐观锁对冲突的解决策略有较复杂的要求，处理不当容易造成系统压力或数据异常，所以与资金相关的金融敏感信息不建议使用乐观锁更新。

正例：悲观锁遵循“一锁二判三更新四释放”的原则

public class ProductDao {
    private JdbcTemplate jdbcTemplate;
    
    // 更新产品价格，使用乐观锁机制
    public boolean updateProductPriceWithRetry(Long productId, BigDecimal newPrice) {
        int retryCount = 0;
        final int maxRetries = 3; // 最少重试3次
        
        while (retryCount < maxRetries) {
            try {
                // 1. 查询当前产品和版本号
                Product product = jdbcTemplate.queryForObject(
                    "SELECT id, name, price, version FROM products WHERE id = ?",
                    (rs, rowNum) -> new Product(
                        rs.getLong("id"),
                        rs.getString("name"),
                        rs.getBigDecimal("price"),
                        rs.getInt("version")
                    ),
                    productId
                );
                // 2. 执行更新操作，带上version条件
                int updatedRows = jdbcTemplate.update(
                    "UPDATE products SET price = ?, version = version + 1 WHERE id = ? AND version = ?",
                    newPrice, productId, product.getVersion()
                );
                // 3. 检查是否更新成功
                if (updatedRows > 0) {
                    return true; // 更新成功
                }
                // 4. 如果没有更新任何行，说明version不匹配，数据已被其他事务修改
                retryCount++;
                Thread.sleep(100); // 短暂等待后重试
                
            } catch (EmptyResultDataAccessException e) {
                // 产品不存在
                return false;
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("更新被中断", e);
            }
        }
        // 重试3次后仍然失败
        throw new OptimisticLockingFailureException("更新产品价格失败，经过" + maxRetries + "次重试后仍无法完成");
    }
}
// 产品实体类
class Product {
    private Long id;
    private String name;
    private BigDecimal price;
    private int version;
    // 构造方法、getter和setter省略
}

使用CountDownLatch进行异步转同步操作，每个线程在退出前必须调用countDown方法，线程执行代码注意catch异常，确保countDown方法被执行到，避免主线程无法执行至await方法，直到超时才返回结果。

说明：子线程抛出异常堆栈，不能在主线程try-catch到。
避免Random实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed导致性能下降。

说明：Random实例包括java.util.Random的实例或者Math. random()的方式。正例：在JDK 7之后，可以直接使用API ThreadLocalRandom；而在JDK 7之前，需要编码保证每个线程持有一个单独的Random实例。
ThreadLocal对象使用static修饰，Thread Local无法解决共享对象的更新问题。

说明：这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变量，也就是说，在类第一次被使用时装载，只分配一块存储空间，所有此类的对象（只要是这个线程内定义的）都可以操控这个变量。

1.8 控制语句

在一个switch块内，每个case要么通过continue/ break/return等终止，要么注释说明程序将继续执行到哪一个case为止。一个switch块内必须包含一个default语句并且放在最后，即使它什么代码也没有。

说明：break是退出switch语句块，而return是退出方法体。
当switch括号内的变量类型为String并且此变量为外部参数时，必须先进行null判断。
在三目运算符condition? 表达式1 : 表达式2中，注意表达式1和表达式2在类型对齐时，可能抛出自动拆箱导致的NPE异常。

说明：以下两种场景会触发类型对齐的拆箱操作：

1）表达式1或表达式2的值有一个是原始类型。

2）表达式1或表达式2的值的类型不一致，会强制拆箱升级成表示范围更大的那个类型。
在高并发场景中，避免使用“等于”判断作为中断或退出的条件。

说明：如果没有处理好并发控制，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。

反例：当判断剩余奖品数量等于0时，终止发放奖品，但因为并发处理错误，导致奖品数量瞬间变成了负数，这样的话活动将无法终止。
表达异常的分支时，尽量少用if-else方式，这种方式可以改写成：

说明：如果不得不使用if()…else if()…else…方式表达逻辑，那么为【强制】避免后续代码维护困难，请勿超过3层。
除常用方法（如getXxx/isXxx）外，不要在条件判断中执行其他复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。

说明：很多if语句内的逻辑表达式相当复杂，与、或、取反混合运算，甚至各种方法纵深调用，理解成本非常高。如果赋值一个非常好理解的布尔变量名字，则是件令人赏心悦目的事情。
不要在其他表达式（尤其是条件表达式）中插入赋值语句。

说明：赋值点类似于人体的穴位，对于代码的理解至关重要，所以赋值语句需要清晰地单独成为一行。
避免采用取反逻辑运算符。

说明：取反逻辑不利于快速理解，并且取反逻辑写法一般都存在对应的正向逻辑写法。
公开接口需要进行入参保护，尤其是批量操作的接口。

反例：某业务系统，提供一个用户批量查询的接口，API文档上有说最多查多少个，但接口实现上没做任何保护，导致调用方传了一个1000的用户id数组，查询信息后，内存爆满。

1.9 注释规约

类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用// xxx方式。

说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，当工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。
所有的类都必须添加创建者和创建日期。

说明：在设置模板时，注意IDEA的@author为’${USER}’，而eclipse的@author为’${user}’，大小写有区别。日期的设置统一为yyyy/MM/dd的格式。
与其用“半吊子”英文注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

反例：将“TCP连接超时”解释成“传输控制协议连接超时”，理解起来反而费脑筋。
谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明：代码被注释掉有两种可能：

1）后续会恢复此段代码逻辑；

2）永久不用。

前者如果没有备注信息，则难以知晓注释动机。后者建议直接删除，假如需要查阅历史代码，登录代码仓库即可。
对于注释的要求。

1）能够准确反映设计思想和代码逻辑。

2）能够描述业务含义，使其他程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释既是给自己看的，即使隔很长时间，也能清晰理解当时的思路；也是给继任者看的，使其能够快速接替自己的工作。
特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。有时候线上故障就来源于这些标记处的代码。

1）待办事宜（TODO）:（标记人，标记时间，[预计处理时间]）。

表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，虽然目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类、接口和方法（因为它是一个Javadoc标签）。

2）错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）。

在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

1.10 前后端规约

前后端数据列表相关的接口返回，如果为空，则返回空数组[]或空集合{}。

说明：此条约定有利于数据层面上的协作更加高效，减少前端很多琐碎的null判断。

当服务端发生错误时，返回给前端的响应信息必须包含HTTP状态码、errorCode、errorMessage和用户提示信息四部分。

说明：四部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中输出给用户的提示信息要求：简短清晰、提示友好，引导用户进行下一步操作或解释错误原因，提示信息可以包括错误原因、上下文环境、推荐操作等。errorMessage：简要描述后端出错原因，便于错误排查人员快速定位问题，注意不要包含敏感数据信息。

正例：常见的HTTP状态码如下。
1）200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。
2）401 Unauthorized: 请求要求身份验证，常见于需要登录而用户未登录的情况。
3）403 Forbidden：服务器拒绝请求，常见于机密信息或通过复制其他登录用户链接访问服务器的情况。
4）404 Not Found: 服务器无法获得所请求的网页，请求资源不存在。
5）500 Internal Server Error: 服务器内部错误。

当HTTP请求通过URL传递参数时，不能超过2048字节。

说明：不同浏览器对于URL的最大长度限制略有不同，并且对超出最大长度的处理逻辑也有差异，2048字节是取所有浏览器的最小值。

反例：某业务将退货的商品id列表放在URL中作为参数传递，当一次退货商品数量过多时，URL参数超长，传递到后端的参数被截断，导致部分商品未能正确退货。
HTTP请求通过body传递内容时，必须控制长度，超出最大长度后，后端解析会出错。

说明：Nginx默认限制为1MB，Tomcat默认限制为2MB，当确实有业务需要传递较多内容时，可以调大服务器端的限制。
服务端返回的数据，使用JSON格式而非XML。

说明：尽管HTTP支持使用不同的输出格式，例如纯文本、JSON、CSV、XML、RSS甚至HTML。但如果我们使用面向用户的服务，那么应该选择JSON
前后端的时间格式统一为”yyyy-MM-dd HH:mm:ss”，为GMT。

1.11　其他

避免用Apache Beanutils进行属性的copy。

说明：Apache BeanUtils性能较差，可以使用其他方案，比如Spring BeanUtils、Cglib BeanCopier，注意均是浅拷贝。
注意Math.random()方法返回的是double类型，取值的范围0≤x<1（能够取到零值，注意除零异常）。如果想获取整数类型的随机数，不要将x放大10的若干倍后再取整，直接使用Random对象的nextInt或者nextLong方法即可。
不要在视图模板中加入任何复杂的逻辑。

说明：根据MVC理论，视图的职责是展示，不要抢模型和控制器的工作。
及时清理不再使用的代码段或配置信息。

说明：对于垃圾代码或过时配置，坚决清理干净，避免程序过度臃肿，代码冗余。

第2章　异常日志

异常处理是大部分程序员多年的痛点，本章主要涉及如何定义错误码，定义异常对象、捕获、处理异常事件，如何以合理的日志结构保存出错现场信息，以便快速定位问题。

2.1　错误码

错误码的制订原则：快速溯源、沟通标准化。

说明：错误码设计得过于完美和复杂，就像字典中的生僻字一样，虽然表意精准，但是不易懂。

正例：错误码回答“谁的错？”“错在哪？”的问题。

1）错误码必须能够快速知晓错误来源，可快速判断是谁的问题。

2）错误码必须能够清晰地比对（代码中容易equals）。

3）错误码有利于团队快速对错误原因达成一致。
当全部正常，但不得不填充错误码时，返回五个零（00000）。
错误码为字符串类型，共5位，分为错误产生来源、四位数字编号两部分。

说明：错误产生来源分为A、B、C三种，A表示错误来源于用户，例如参数错误、用户安装版本过低、用户支付超时等；B表示错误来源于当前系统，例如业务逻辑出错、程序健壮性差等；C表示错误来源于第三方服务，例如CDN服务出错、消息投递超时等；四位数字编号从0001到9999，大类之间的步长间距预留100。
错误码使用者避免随意定义新的错误码。

说明：在代码中使用错误码时，尽可能在原有错误码附表中找到语义相同或者相近的错误码。
错误码不能直接输出给用户作为提示信息使用。

说明：堆栈、错误码（errorCode）、错误信息(errorMessage)、提示信息（userTip）是一个有效关联并互相转义的和谐整体，但请勿越俎代庖。
错误码分为一级宏观错误码、二级宏观错误码、三级宏观错误码。

说明：在无法确定的错误场景中，可以直接使用一级宏观错误码，分别是：A0001（用户端错误）、B0001（系统执行出错）、C0001（调用第三方服务出错）。

正例：调用第三方服务出错是一级，中间件出错是二级，消息服务出错是三级。

2.2　异常处理

Java类库中定义的可以通过预检查方式规避的RuntimeException不应该通过catch的方式处理，如：NullPointerException、IndexOutOfBoundsException等。

说明：无法通过预检查的异常不在此列，比如当解析字符串形式的数字时，可能存在数字格式错误，通过catch NumberFormatException实现。
1
2
正例：if (obj!=null) {...}
反例：try { obj.method(); } catch(NullPointerException e){...}
异常被捕获后不要用来做流程控制和条件控制。

catch时请分清稳定代码和非稳定代码。稳定代码一般指本机运行且执行结果确定性高的代码。对于非稳定代码的catch，尽可能在进行异常类型的区分后，再做对应的异常处理。

说明：对大段代码进行try-catch，将使程序无法根据不同的异常做出正确的“应激”反应，也不利于定位问题，这是一种不负责任的表现。

（1）稳定代码示例

稳定代码通常指在本机运行且执行结果确定性高的代码，例如简单的数学运算或确定性的数据处理。

// 稳定代码示例 - 简单的数学计算
public int calculateCircleArea(int radius) {
    // 这是一个确定性很高的计算
    return (int)(Math.PI * radius * radius);
}
// 调用稳定代码时，通常不需要try-catch
public void useStableCode() {
    int radius = 5;
    int area = calculateCircleArea(radius);
    System.out.println("Area: " + area);
}

对于这种稳定代码，不需要使用try-catch，因为：

所有操作都是确定性的
不会抛出意外异常
参数类型和范围可以通过前置条件检查

（2）非稳定代码示例

非稳定代码通常涉及外部依赖或不确定因素，如网络请求、文件IO、数据库操作等。

// 非稳定代码示例 - 从网络获取数据
public String fetchDataFromAPI(String url) throws IOException, APIException {
    // 这里可能有多种异常情况
    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .build();
    HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() != 200) {
        throw new APIException("API returned status: " + response.statusCode());
    }
    return response.body();
}

// 调用非稳定代码时，应该区分处理不同异常
public void useUnstableCode() {
    String apiUrl = "https://api.example.com/data";
    try {
        String data = fetchDataFromAPI(apiUrl);
        processData(data);
    } catch (IOException e) {
        // 处理网络或IO相关异常
        System.err.println("Network error: " + e.getMessage());
        // 可能的恢复操作，如重试或使用缓存
    } catch (APIException e) {
        // 处理API特定的业务异常
        System.err.println("API error: " + e.getMessage());
        // 可能的恢复操作，如使用备用API
    } catch (Exception e) {
        // 捕获其他未预期的异常
        System.err.println("Unexpected error: " + e.getMessage());
        // 记录日志并优雅降级
    }
}

对于非稳定代码，应该：

区分不同类型的异常
为每种异常提供适当的处理或恢复策略
避免笼统的捕获所有异常
在最外层提供适当的错误反馈机制

（3）不良实践示例（应避免）

// 不好的做法 - 大段代码笼统try-catch
public void badPractice() {
    try {
        // 包含多种操作的代码块
        String data = fetchDataFromAPI("https://api.example.com/data");
        processData(data);
        saveToDatabase(data);
        sendNotification();
    } catch (Exception e) { // 捕获所有异常
        System.out.println("Something went wrong");
    }
}

这种做法的缺点：

无法区分不同类型的错误
无法针对特定错误采取特定恢复措施
不利于问题定位和调试
用户体验差（只有笼统的错误信息）

捕获异常是为了处理异常，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者必须处理异常，将其转化为用户可以理解的内容。
finally块必须对资源对象、流对象进行关闭操作，如果有异常就要做try-catch操作。

说明：对于JDK 7及以上版本，可以使用try-with-resources方式。
不要在finally块中使用return。

说明：try块中的return语句执行成功后，并不马上返回，而是继续执行finally块中的语句，如果此处存在return语句，则在此直接返回，无情地丢弃try块中的返回点。
捕获异常与抛异常必须完全匹配，或者捕获异常是抛异常的父类。

说明：如果预计对方抛的是绣球，实际接到的是铅球，就会产生意外。
防止产生NPE是程序员的基本修养，注意NPE产生的场景。

说明：本手册明确，防止产生NPE是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null值的情况。

1）当返回类型为基本数据类型，return包装数据类型的对象时，自动拆箱有可能产生NPE。

反例：public int f() { return Integer对象}，如果为null，则自动拆箱，抛NPE。

2）数据库的查询结果可能为null。

3）集合里的元素即使isNotEmpty，取出的数据元素也可能为null。

4）当远程调用返回对象时，一律要求进行空指针判断，以防止产生NPE。

5）对于Session中获取的数据，建议进行NPE检查，以避免空指针。

6）级联调用obj.getA().getB().getC()；的一连串调用，易产生NPE。

正例：使用JDK 8的Optional类防止产生NPE。
定义时区分unchecked / checked异常，避免直接抛出new RuntimeException()，更不允许抛出Exception或者Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException / ServiceException等。

2.3　日志规约

应用中不可直接使用日志系统（Log4j、Logback）中的API，而应依赖使用日志框架（SLF4J、JCL–Jakarta Commons Logging）中的API，使用门面模式的日志框架，有利于维护日志并保证各个类的日志处理方式统一。
所有日志文件至少保存15天，因为有些异常具备以“周”为频次发生的特点。对于当天日志，以“应用名.log”保存在“/home/admin/应用名/logs/”目录下，过往日志格式： {logname}.log.{保存日期}，日期格式：yyyy-MM-dd。

应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：appName_logType_logName.log。logType为日志类型，如stats/monitor/access等；logName为日志描述。这种命名的好处是通过文件名就可以知道日志文件属于哪个应用，哪种类型，有什么目的，这也有利于归类查找。

说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，既便于开发人员查看，也便于通过日志及时监控系统。

下面是一个完整的基于SLF4J+Logback实现错误日志和业务日志分离的示例，包含配置和代码实现。

1. Maven依赖配置

首先确保pom.xml中包含必要的依赖：

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.7</version>
    </dependency>
    
    <!-- Logback实现 -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.7</version>
    </dependency>
</dependencies>

2. Logback配置文件 (logback.xml)

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- 定义日志存储目录 -->
    <property name="LOG_DIR" value="./logs" />
    
    <!-- 公共日志格式 -->
    <property name="COMMON_PATTERN" 
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n" />
    
    <!-- 业务日志Appender -->
    <appender name="BUSINESS" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_DIR}/business.log</file>
        <encoder>
            <pattern>${COMMON_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/business.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
    </appender>
    
    <!-- 错误日志Appender -->
    <appender name="ERROR" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_DIR}/error.log</file>
        <encoder>
            <pattern>${COMMON_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/error.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>90</maxHistory> <!-- 错误日志保留更久 -->
        </rollingPolicy>
    </appender>
    
    <!-- 业务日志Logger配置 -->
    <logger name="com.example.business" level="INFO" additivity="false">
        <appender-ref ref="BUSINESS" />
    </logger>
    
    <!-- 系统错误日志配置 -->
    <root level="ERROR">
        <appender-ref ref="ERROR" />
    </root>
</configuration>

3. Java代码实现示例

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class OrderService {
    // 业务日志Logger - 使用特定包名
    private static final Logger businessLogger = 
            LoggerFactory.getLogger("com.example.business.OrderService");
    
    // 错误日志Logger - 使用类名(会被root logger捕获)
    private static final Logger errorLogger = 
            LoggerFactory.getLogger(OrderService.class);
    
    public void processOrder(Order order) {
        try {
            // 业务日志记录
            businessLogger.info("开始处理订单, 订单ID: {}", order.getId());
            businessLogger.debug("订单详情: {}", order.toString());
            
            // 业务逻辑处理...
            
            businessLogger.info("订单处理完成, 订单ID: {}", order.getId());
        } catch (Exception e) {
            // 错误日志记录
            errorLogger.error("处理订单异常, 订单ID: " + order.getId(), e);
            
            // 同时也可以在业务日志中记录错误(可选)
            businessLogger.warn("订单处理失败, 订单ID: {}, 原因: {}", 
                    order.getId(), e.getMessage());
        }
    }
}

// 另一个服务示例
public class PaymentService {
    // 业务日志Logger
    private static final Logger businessLogger = 
            LoggerFactory.getLogger("com.example.business.PaymentService");
    
    // 错误日志Logger
    private static final Logger errorLogger = 
            LoggerFactory.getLogger(PaymentService.class);
    
    public void processPayment(Payment payment) {
        businessLogger.info("开始处理支付, 支付单号: {}", payment.getTransactionId());
        
        try {
            // 支付处理逻辑...
        } catch (PaymentException e) {
            errorLogger.error("支付处理失败, 交易号: {}, 错误码: {}", 
                    payment.getTransactionId(), e.getErrorCode(), e);
        }
    }
}

4. 高级配置建议

多环境配置：可以为不同环境(dev/test/prod)配置不同的日志级别和输出方式
日志文件大小控制：可以添加SizeBasedTriggeringPolicy控制单个日志文件大小
异步日志：对于高性能场景，可以使用AsyncAppender
MDC应用：可以在业务日志中添加追踪ID等上下文信息

<!-- 异步日志配置示例 -->
<appender name="ASYNC_BUSINESS" class="ch.qos.logback.classic.AsyncAppender">
    <queueSize>1024</queueSize>
    <discardingThreshold>0</discardingThreshold>
    <appender-ref ref="BUSINESS" />
</appender>

这种分离方式使得：

所有业务日志会记录到business.log文件中
所有ERROR级别日志会记录到error.log文件中
开发人员可以专注于查看业务日志
运维人员可以监控error.log快速发现问题

当输出日志时，字符串变量之间的拼接使用占位符的方式。

说明：因为String字符串的拼接会使用StringBuilder的append()方式，所以有一定的性能损耗。使用占位符仅是替换动作，可以有效提升性能。
1
logger.debug("Processing trade with id : {} and symbol: {}",id,symbol);
在生产环境中禁止直接使用System.out或System. err输出日志，或使用e.printStackTrace()打印异常堆栈。
异常信息应该包括两类：案发现场信息和异常堆栈信息。如果不处理，那么通过关键字throws往上抛出。
1
logger.error("inputParams:{} and errorMessage: {}",各类参数或者对象.toString(), e,getMessage(),e)
打印日志时，禁止直接用JSON工具将对象转换成String。

正例：打印日志时，仅打印业务相关属性值或者调用其对象的toString()方法。

说明：如果对象里某些get方法被覆写，存在抛出异常的情况，则可能会因为打印日志而影响正常的业务流程的执行。
谨慎地记录日志。在生产环境中禁止输出debug日志；有选择地输出info日志；如果使用warn记录刚上线时的业务行为信息，则一定要注意日志输出量的问题，避免把服务器磁盘撑爆，并及时删除这些观察日志。

说明：大量地输出无效日志，既不利于提升系统性能，也不利于快速定位错误点。记录日志时请思考：这些日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？
可以使用warn日志级别记录用户输入参数错误的情况，避免当用户投诉时无所适从。

说明：如非必要，请不要在此场景中打出error级别，避免频繁报警。注意日志输出的级别，error级别只记录系统逻辑出错、异常等重要的错误信息。

第3章　单元测试

什么是好的单元测试标准？如何写好单元测试？本章首次提出AIR原则和BCDE原则进行衡量。

单元测试应该是全自动执行的，并且是非交互式的。测试用例通常是被定期执行的，执行过程必须完全自动化才有意义。需要人工检查输出结果的测试不是好的单元测试。单元测试中不准使用System.out进行人肉验证，必须使用assert验证。
保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。

反例：method2需要依赖method1的执行，将执行结果作为method2的输入。
对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单元测试粒度至多是类级别，一般是方法级别。

说明：只有测试粒度足够小，才能在出错时尽快定位到出错位置。单元测试不负责检查跨类或者跨系统的交互逻辑，那是集成测试的领域。
【重要】核心业务、核心应用、核心模块的增量代码确保通过单元测试。

说明：新增代码及时补充单元测试，如果新增代码影响了原有单元测试，请及时修正。
单元测试代码必须写在如下工程目录下：src/test/ java，不允许写在业务代码目录下。

说明：源码编译时会跳过此目录，而单元测试框架默认扫描此目录。
单元测试的基本目标：语句覆盖率达到70%；核心模块的语句覆盖率和分支覆盖率都要达到100%。

说明：在工程规约的应用分层中提到的DAO层、Manager层、可重用度高的Service层，都应该进行单元测试。
编写单元测试代码遵守BCDE原则，以保证被测试模块的交付质量。
- B：Border，边界值测试，包括循环边界、特殊取值、特殊时间点和数据顺序等。
- C：Correct，正确地输入，并得到预期的结果。
- D：Design，与设计文档相结合，编写单元测试。
- E：Error，强制错误信息输入（如：非法数据、异常流程、业务允许输入等），并得到预期的结果。
和数据库相关的单元测试，可以设定自动回滚机制，不给数据库造成脏数据。或者对单元测试产生的数据有明确的前后缀标识。

正例：在阿里云的内部单元测试中，使用ALIYUN_UNIT_TEST_的前缀来标识单元测试相关代码。
作为一种质量保障手段，不建议项目发布后补充单元测试用例，建议在项目提测前完成单元测试。
为了更方便地进行单元测试，业务代码应避免出现以下情况。

1）构造方法中做的事情过多。

2）存在过多的全局变量和静态方法。

3）存在过多的外部依赖。

4）存在过多的条件语句。

说明：多层条件语句建议使用卫语句、策略模式、状态模式等方式重构。
不要对单元测试存在如下误解：

1）那是测试工程师干的事情。本书是开发手册，凡是本书内容，都是与开发工程师强相关的。

2）单元测试代码是多余的。系统的整体功能与各单元部件的测试正常与否是强相关的。

3）单元测试代码不需要维护。如果不维护，那么一年半载后，单元测试几乎处于废弃状态。

4）单元测试与线上故障没有辩证关系。好的单元测试能够最大限度地规避线上故障。

第4章安全规约

“安全生产，责任重于泰山。”这句话同样适用于软件生产场景中，本章主要说明编程中需要注意的安全准则。

隶属于用户个人的页面或者功能必须进行权限控制校验。

说明：防止没有做水平权限校验就可以随意访问、修改、删除别人的数据，比如查看他人的私信内容。
用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

说明：个人手机号码显示为137****0969，隐藏中间4位，防止隐私泄露。
用户输入的SQL参数严格使用参数绑定或者METADATA字段值限定，防止SQL注入，禁止字符串拼接SQL访问数据库。

反例：某系统没有对危险字符 # –进行转义，导致在更新数据库时，where后边的信息被注释掉，对全库进行了更新，从而造成大量系统签名被恶意修改。
用户请求传入的任何参数必须做有效性验证。

说明：忽略参数校验可能导致如下情况。

1）page size过大导致内存溢出。

2）恶意order by导致数据库慢查询。

3）缓存击穿。

4）SSRF。

5）任意重定向。

6）SQL注入、Shell注入和反序列化注入。

7）正则输入源串拒绝服务ReDoS。

Java代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使用特殊构造的字符串来验证，则有可能导致死循环。
在提交表单、AJAX时须执行CSRF安全验证。

说明：CSRF(Cross-Site Request Forgery)跨站请求伪造是一类常见的编程漏洞。对于存在CSRF漏洞的应用或网站，攻击者可以事先构造好URL，一旦用户访问，后台便可在其不知情的情况下对数据库中的用户参数进行相应的修改。
URL外部重定向传入的目标地址必须执行白名单过滤。
在使用平台资源时，例如短信、邮件、电话、下单、支付，必须实现正确的防重放的机制，如数量限制、疲劳度控制、验证码校验，避免被滥刷导致用户受扰或平台资损。

说明：例如，注册时将验证码发送到手机，如果没有限制次数和频率，那么可以利用此功能骚扰其他用户，并造成短信平台资源浪费。
针对发帖、评论、发送即时消息等用户生成内容的场景，必须实行防刷、文本内容违禁词过滤等风控策略。

第5章　MySQL数据库

底层数据库的规范有助于降低软件实现的复杂度，降低沟通成本。本章主要说明建表规范、索引优化准则及ORM层的处理约定。ORM（Object-Relational Mapping）层是应用程序架构中负责处理对象与关系型数据库之间映射的组件层，它位于业务逻辑层和数据访问层之间。

ORM层的核心作用：

桥梁作用：将面向对象的编程语言与关系型数据库连接起来
转换功能：实现数据库表记录↔编程语言对象的双向转换
抽象封装：隐藏底层SQL操作细节，提供面向对象的数据库访问接口

优势：

提高开发效率，减少重复SQL编写
使代码更面向对象，提高可维护性
提供跨数据库支持（通过方言机制）
内置安全机制防止SQL注入

局限：

学习曲线较陡峭
复杂查询可能性能不如手写SQL
过度抽象可能导致调试困难
不合理的映射设计可能引发N+1查询问题

ORM层工作流程示例

// 1. 定义实体类（对象-表映射）
@Entity
@Table(name = "employees")
public class Employee {
    @Id
    @GeneratedValue
    private Long id;
    
    @Column(name = "emp_name")
    private String name;
    
    // 关联部门（关系映射）
    @ManyToOne
    @JoinColumn(name = "dept_id")
    private Department department;
}

// 2. ORM操作示例
public class EmployeeService {
    public void updateEmployeeDepartment(Long empId, Long deptId) {
        // 开启事务（ORM事务管理）
        Transaction tx = session.beginTransaction();
        
        try {
            // 查询员工（自动生成SELECT语句）
            Employee emp = session.get(Employee.class, empId);
            
            // 查询部门
            Department dept = session.get(Department.class, deptId);
            
            // 更新关联（自动处理外键关系）
            emp.setDepartment(dept);
            
            // 提交事务（自动生成UPDATE语句）
            tx.commit();
        } catch (Exception e) {
            tx.rollback();
        }
    }
}

5.1　建表规约

表达是与否概念的字段，必须使用is_xxx的方式命名，数据类型是unsigned tinyint（1表示是，0表示否）。

说明：任何字段如果为非负数，则必须是unsigned。

注意：POJO类中的任何布尔类型的变量，都不要加is前缀，需要在中设置从is_xxx到xxx的映射关系。数据库表示是与否的值，使用tinyint类型，坚持is_xxx的命名方式是为了明确其取值含义与取值范围。

正例：表达逻辑删除的字段名is_deleted，1表示删除，0表示未删除。
【重要】表名、字段名必须使用小写字母或数字，禁止出现数字开头，禁止两个下画线中间只出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。

说明：MySQL在Windows系统中不区分大小写，但在Linux系统中默认区分大小写。因此，数据库名、表名和字段名，都不允许出现任何大写字母，避免节外生枝。
1
2
正例：aliyun_adminr，dc_config，level3_name
反例：AliyunAdmin，rdcConfig，level_3_name
主键索引名为pk_字段名，唯一索引名为uk_字段名，普通索引名则为idx_字段名。
1
说明：pk_即primary key，uk_即unique key，idx_即index的简称。
小数类型为decimal，禁止使用float和double类型。

说明：在存储时，float和double类型存在精度损失的问题，很可能在比较值的时候，得到不正确的结果。如果存储的数据范围超过decimal的范围，那么建议将数据拆成整数和小数并分开存储。
如果存储的字符串长度几乎相等，则使用char定长字符串类型。
varchar是可变长字符串，不预先分配存储空间，长度不要超过5000个字符，如果存储长度大于此值，则应定义字段类型为text，独立出来一张表，用主键来对应，避免影响其他字段的索引效率。
【重要】表必备三字段：id、create_time、update_time。

说明：其中id必为主键，类型为bigint unsigned、单表时自增、步长为1。create_time和update_time的类型均为date_time。
表的命名最好遵循“业务名称_表的作用”原则。
1
正例：alipay_task/force_project/trade_config
字段允许适当冗余，以提高查询性能，但必须考虑数据一致性。冗余字段应遵循以下原则。

1）不是频繁修改的字段。

2）不是唯一索引的字段。

3）不是varchar超长字段，更不能是text字段。

正例：各业务线经常冗余存储商品名称，避免查询时需要调用基础服务获取。

5.2　索引规约

业务上具有唯一特性的字段，即使是多个字段的组合，也必须建成唯一索引。

说明：不要以为唯一索引影响了insert速度，这个速度损耗可以忽略，但会明显提高查找速度；另外，即使在应用层做了非常完善的校验控制，只要没有唯一索引，根据墨菲定律，就必然有脏数据产生。
超过三个表禁止join。需要join的字段，数据类型必须绝对一致；当多表关联查询时，保证被关联的字段需要有索引。

说明：即使双表join，也要注意表索引、SQL性能。
在varchar字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据实际文本区分度决定索引长度即可。

说明：索引的长度与区分度是一对矛盾体，一般对于字符串类型数据，长度为20的索引，区分度会高达90%以上，可以使用count(distinct left(列名, 索引长度))/count(*)的区分度来确定。
利用覆盖索引进行查询操作，避免回表。

说明：如果想知道一本书的第11章是什么标题，我们有必要翻开第11章对应的那一页吗？只要浏览一下目录就好，这个目录就起到覆盖索引的作用。

正例：能够建立索引的种类分为主键索引、唯一索引、普通索引3种，而覆盖索引只是查询的一种效果，用explain的结果，extra列会出现“using index”。

利用延迟关联或者子查询优化超多分页场景。

说明：MySQL并不是跳过offset行，而是取offset+N行，然后返回放弃前offset行，返回N行。当offset特别大的时候，效率会非常低，要么控制返回的总页数，要么对超过特定阈值的页数进行SQL改写。

问题背景理解
MySQL的LIMIT分页机制在处理大数据量时存在性能问题，特别是当offset值很大时。这是因为MySQL的执行方式不是”跳过”offset行，而是”先取offset+N行，然后丢弃前offset行”。

原始分页查询的问题
1
2
-- 传统分页查询（offset很大时性能差）
SELECT * FROM large_table ORDER BY create_time DESC LIMIT 100000, 10;
这个查询的执行过程：

先读取100010行数据（即使你只需要10行）

然后丢弃前100000行

最后返回剩下的10行

优化方案一：延迟关联
优化原理:先通过索引获取主键ID，然后再关联原表获取完整数据。
1
2
3
4
5
6
7
-- 优化后的延迟关联查询
SELECT t.* FROM large_table t
INNER JOIN (
    SELECT id FROM large_table
    ORDER BY create_time DESC
    LIMIT 100000, 10
) AS tmp ON t.id = tmp.id;
执行过程：

子查询只查询ID（利用覆盖索引）

外层查询通过ID关联获取完整数据

大大减少了需要读取的数据量

优化方案二：子查询优化
优化原理:利用主键或唯一索引的特性，先定位到起始位置，再获取后续记录。
1
2
3
4
5
6
7
8
9
-- 子查询优化（假设id是自增主键）
SELECT * FROM large_table
WHERE id >= (
    SELECT id FROM large_table
    ORDER BY create_time DESC
    LIMIT 100000, 1
)
ORDER BY create_time DESC
LIMIT 10;
执行过程：

子查询快速定位到第100000条记录的ID

主查询从该ID开始获取10条记录

避免了扫描和丢弃大量记录

实际案例对比
假设有一个1000万条记录的用户表：

原始查询（性能差）
1
2
-- 执行时间：约2.5秒
SELECT * FROM users ORDER BY register_time DESC LIMIT 999990, 10;
优化后的查询（性能好）
1
2
3
4
5
6
7
-- 执行时间：约0.1秒
SELECT u.* FROM users u
INNER JOIN (
    SELECT user_id FROM users
    ORDER BY register_time DESC
    LIMIT 999990, 10
) AS tmp ON u.user_id = tmp.user_id;
其他优化策略
记录上次查询位置（适用于连续分页）：
1
2
3
4
5
-- 记住上一页最后一条记录的register_time和id
SELECT * FROM users 
WHERE register_time <= '2023-05-20 15:30:00' AND user_id < 12345
ORDER BY register_time DESC, user_id DESC
LIMIT 10;
使用覆盖索引：
1
2
-- 确保排序字段和查询字段都在索引中
ALTER TABLE users ADD INDEX idx_register_time_id (register_time, user_id);
业务层面限制：

限制用户只能查看前100页

提供更精确的筛选条件减少数据量
为什么这些优化有效？

减少数据扫描量：延迟关联和子查询都先通过索引获取少量数据

避免全表扫描：利用了索引的有序性

减少内存消耗：不需要在内存中存储大量临时数据

5.3　SQL语句

不要使用count(列名)或count(常量)来替代count()，count()是SQL92定义的标准统计行数的语法，与数据库无关，与NULL和非NULL无关。

说明：count(*)会统计值为NULL的行，而count(列名)不会统计此列值为NULL的行。
count(distinct column) 计算该列除NULL外的不重复行数。注意，count(distinct column1, column2)，如果其中一列全为NULL，那么即使另一列有不同的值，也返回为0。
当某一列的值全为NULL时，count(column)的返回结果为0，但sum(column)的返回结果为NULL，因此使用sum()时需注意避免NPE问题。

正例：可以使用如下方式避免sum的NPE问题：SELECT IFNULL(SUM (column), 0) FROM table;
使用ISNULL()判断是否为NULL值。

说明：NULL与任何值的直接比较都为NULL。在SQL语句中，如果在null前换行，则会降低可读性。select * from table where column1 is null and column3 is not null; 而ISNULL(column)是一个整体，简捷易懂。从性能数据上分析，ISNULL(column)的执行效率更高一些。
不得使用外键与级联，一切外键概念必须在应用层解决。

说明：以学生和成绩的关系为例，学生表中的student_id是主键，成绩表中的student_id为外键。如果更新学生表中的student_id，则同时触发成绩表中的student_id更新，即为级联更新。外键与级联更新适用于单机低并发，不适合分布式、高并发集群；级联更新是强阻塞，存在数据库更新风暴的风险；外键影响数据库的插入速度。
对于数据库中表记录的查询和变更，只要涉及多个表，就需要在列名前加表的别名（或表名）进行限定。

说明：对多表进行查询记录、更新记录、删除记录时，如果对操作列没有限定表的别名（或表名），并且操作列在多个表中存在，就会抛异常。
in操作能避免则避免，若实在避免不了，则需要仔细评估in后面的集合元素数量，控制在1000之内。
如果有国际化需要，那么所有的字符存储与表示，均以UTF-8编码，注意字符统计函数的区别。

说明：SELECT LENGTH(“轻松工作”)；返回为12。

SELECT CHARACTER_LENGTH(“轻松工作”)；返回为4。

如果需要存储表情，那么选择utf8mb4进行存储，注意它与UTF-8编码的区别。

5.4　ORM映射

在表查询中，一律不要使用 * 作为查询的字段列表，需要哪些字段必须明确写明。

说明：

1）增加查询分析器解析成本。

2）增减字段容易与resultMap配置不一致。

3）多余字段增加网络开销，尤其是text类型的字段。
POJO类的布尔属性不能加is，而数据库字段必须加is_，要求在resultMap中进行字段与属性之间的映射。

说明：参见POJO类及数据库字段定义规定，在sql.xml中必须增加映射。
【重要】不要用resultClass作为返回参数，即使所有类属性名与数据库字段一一对应，也需要定义；反过来，每个表也必然有一个与之对应。

说明：配置映射关系，使字段与DO类解耦，方便维护。
【重要】sql.xml配置参数使用：#{}，#param#，不要使用${}，此种方式容易出现SQL注入。
不允许直接将HashMap与Hashtable作为查询结果集的输出。

反例：某工程师为避免写一个xxx </result Map>，直接使用HashTable接收数据库返回结果，结果由于数据库版本不一样，出现日常把bigint转成Long值，而线上把bigint解析成BigInteger的现象，导致线上出现问题。
@Transactional事务不要滥用。事务会影响数据库的QPS，另外，使用事务的地方需要考虑各方面的回滚方案，包括缓存回滚、搜索引擎回滚、消息补偿和统计修正等。

第6章　工程结构

应用分层的百花齐放，导致对于分层与领域模型的理解多样化，非常不利于团队合作。本章主要说明应用工程分层思想、二方库约定及基本的服务器知识。

6.1　应用分层

根据业务架构实践，结合业界分层规范与流行技术框架分析，推荐分层结构如图6-1所示，默认上层依赖于下层，箭头关系表示可直接依赖，如：开放API层可以依赖于请求处理层（Web层），也可以直接依赖业务逻辑层（Service层），以此类推。

1）开放API层：可直接封装Service接口暴露成HSF接口，通过Web封装成HTTP接口、网关控制层等。

2）终端显示层：各个端的模板渲染并执行显示层。当前主要是velocity渲染、JS渲染、JSP渲染和移动端展示层等。

3）请求处理层（Web层）：主要转发访问控制，校验各类基本参数，或者简单处理不复用的业务等。

4）业务逻辑层（Service层）：相对具体的业务逻辑服务层。

5）通用逻辑层（Manager层）：有如下特征。
- 对第三方平台封装的层，预处理返回结果及转化异常信息，适配上层接口；
- 对Service层通用能力的下沉，如缓存方案、中间件通用处理；
- 与DAO层交互，对DAO的业务通用能力的封装。
6）数据持久层（DAO层）：与底层MySQL、Oracle、HBase和OB进行数据交互。

7）第三方服务：包括其他部门RPC服务接口、基础平台、其他公司的HTTP接口，如淘宝开发平台、支付宝付款服务、高德地图服务等。

8）外部数据接口：外部（应用）数据存储服务提供的接口，多见于数据迁移场景中。
（分层异常处理规约）在DAO层，产生的异常类型有很多，无法用细粒度的异常进行catch，使用catch(Exception e)方式，并throw new DAOException(e)，不需要打印日志。因为日志在Manager/Service层，一定需要捕获并写到日志文件中去，如果同台服务器再写日志，则会降低性能和浪费存储。当Service层出现异常时，必须将出错日志记录到磁盘，尽可能带上参数信息，相当于保护案发现场。如果Manager层与Service层同机部署，则日志方式与DAO层处理一致；如果是单独部署，则采用与Service一致的处理方式。Web层绝不应该继续往上抛异常，因为已经处于顶层，如果意识到该异常将导致页面无法正常渲染，应该直接跳转到友好错误页面，加上用户容易理解的错误提示信息。开放接口层需要将异常处理成errorCode和errorMessage的方式返回。
分层领域模型规约。

1）DO（Data Object）：与数据库表结构一一对应，通过DAO层向上传输数据源对象。

2）DTO（Data Transfer Object）：数据传输对象，Service层或Manager层向外传输的对象。

3）BO（Business Object）：业务对象，可以由Service层输出的封装业务逻辑的对象。

4）Query：数据查询对象，各层接收上层的查询请求。注意，【强制】如果超过2个参数的查询封装，则禁止使用Map类传输。

5）VO（View Object）：显示层对象，通常是Web层向模板渲染引擎层传输的对象。

6.2　二方库依赖

定义GAV遵从以下规则：

1）GroupID格式：com.{公司/BU }.业务线.[子业务线]，最多4级。

说明：{公司/BU}，例如：alibaba/taobao/tmall/aliex press等BU一级；子业务线可选。

2）ArtifactID格式：产品线名-模块名。语义不重复不遗漏，先到中央仓库进行查证。
1
正例：doubao-client/fastjson-api/jstorm-tool
二方库版本号命名方式：主版本号.次版本号.修订号。

1）主版本号：产品方向改变，或者大规模API不兼容，或者架构不兼容升级。

2）次版本号：保持相对兼容性，增加主要功能特性，影响范围极小的API不兼容修改。

3）修订号：保持完全兼容性，修复BUG、新增次要功能特性等。

说明：注意起始版本号必须为：.0.0，而不是0.0.1。

反例：仓库内某二方库版本号从1.0.0.0开始，一直默默“升级”到1.0.0.64，完全失去版本的语义信息。
二方库的新增或升级，保持除功能点外的其他jar包仲裁结果不变。如果有改变，则必须明确评估和验证。

说明：在升级时，进行dependency:resolve前后信息比对，如果仲裁结果完全不一致，那么通过dependency:tree命令，找出差异点，进行排除jar包。
二方库里可以定义枚举类型，参数可以使用枚举类型，但是接口返回值不允许使用枚举类型或者包含枚举类型的POJO对象。
依赖于一个二方库群时，必须定义一个统一的版本变量，避免版本号不一致。

说明：依赖springframework-core、-context、-beans，它们都是同一个版本，可以定义一个变量来保存版本${spring.version}。定义依赖的时候，引用该版本。
禁止在子项目的pom依赖中出现相同的GroupId，相同的ArtifactId，但是不同的Version。

说明：在本地调试时会使用各子项目指定的版本号，但是当合并成一个war时，只能有一个版本号出现在最后的lib目录中。可能会出现在线下调试时是正确的，发布到线上却出故障的问题。
所有pom文件中的依赖声明放在语句块中，所有版本仲裁放在语句块中。

说明：里只是声明版本，并不实现引入，因此子项目需要显式的声明依赖，version和scope都读取自父pom。而所有声明在主pom的里的依赖都会自动引入，并默认被所有的子项目继承。

6.3　服务器

高并发服务器建议调小TCP协议的time_wait超时时间。

说明：操作系统默认240s后，才会关闭处于time_wait状态的连接。在高并发访问场景下，服务器端会因为处于time_wait的连接数过多，而无法建立新的连接，所以需要在服务器上调小此等待值。
调大服务器所支持的最大文件句柄数，即fd（全称：FileDescriptor）。

说明：主流操作系统的设计是将TCP/UDP连接采用与文件一样的方式管理，即一个连接对应一个fd。主流的Linux服务器默认支持最大的fd数量为1024，当并发连接数很大时，很容易因为fd不足而出现”open too many files”错误，导致新的连接无法建立。建议将Linux服务器所支持的最大句柄数调高数倍（与服务器的内存数量相关）。

第7章　设计规约

诚如序言所讲，程序员是天生的艺术家，软件设计能力就是考验“艺术家”成色的试金石。本章主要说明软件设计过程中UML设计准则及基本的架构理念。

存储方案和底层数据结构的设计获得评审一致通过，并沉淀成为文档。

说明：有缺陷的底层数据结构容易导致系统风险上升，可扩展性下降，重构成本也会因历史数据迁移和系统平滑过渡而陡然增加，所以对存储方案和数据结构需要认真地设计和评审。生产环境提交执行后，团队成员需要进行double check。

正例：评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发展、表或字段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段）也需要评审通过后再上线。
在需求分析阶段，如果与系统交互的User超过1类，并且相关的User Case超过5个，那么使用用例图来表达结构化需求会更加清晰。
如果某个业务对象的状态超过3个，那么应使用状态图表达并且明确状态变化的各个触发条件。

说明：状态图的核心是对象状态，首先明确对象有多少种状态，然后明确两两状态之间是否存在直接转换关系，再明确触发状态转换的条件是什么。

正例：淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。
如果系统中某个功能的调用链路上的涉及对象超过3个，则使用时序图表达并且明确各调用环节的输入与输出。

说明：时序图反映了一系列对象间的交互与协作关系，清晰立体地反映了系统的调用纵深链路。
如果系统中模型类超过5个，并且存在复杂的依赖关系，则应使用类图表达并且明确类之间的关系。

说明：类图就像建筑领域的施工图，如果搭平房，可能不需要，但如果建造“蚂蚁Z空间”大楼，则肯定需要详细的施工图。
如果系统中超过2个对象之间存在协作关系，并且需要表示复杂的处理流程，则使用活动图来表示。

说明：活动图是流程图的扩展，增加了能够体现协作关系的对象泳道，支持并发表示等。
需求分析与系统设计在考虑主干功能的同时，需要充分评估异常流程与业务边界。

反例：用户在淘宝付款过程中，银行扣款成功，发送给用户扣款成功短信，但是在支付宝入款时由于断网演练产生异常，淘宝订单页面依然显示未付款，导致用户投诉。
类在设计与实现时要符合单一原则。

说明：单一原则是最易理解却又最难实现的一条规则，随着系统演进，工程师很多时候会忘记类设计的初衷。
谨慎使用继承的方式进行扩展，优先使用聚合或组合的方式来实现。

说明：若一定要使用继承，则必须符合里氏代换原则，此原则要求在父类能够出现的地方子类一定能够出现，比如“把钱交出来”中，美元、欧元、人民币等钱的子类都可以出现。
避免发生如下误解：敏捷开发=讲故事+编码+发布。

说明：敏捷开发是快速交付迭代可用的系统，省略多余的设计方案，摒弃传统的审批流程，但在核心或关键模块上，必须进行必要的设计和文档的沉淀。

反例：为了确保业务快速发展，敏捷成了某团队产品经理催进度的借口，系统中均是勉强能运行但像面条一样的代码，可维护性和可扩展性极差，一年之后，不得不进行大规模重构，得不偿失。
系统设计文档的主要目的是明确需求、理顺逻辑、后期维护，次要目的是指导编码。

说明：避免为了设计而设计，系统设计文档应有助于后期的系统维护和重构，所以设计结果需要进行分类归档保存。
设计的本质就是识别和表达系统难点。

说明：识别和表达完全是两回事，很多人错误地认为只要识别到系统难点在哪里，表达只是自然而然的事情，但是大家在设计评审时经常出现语焉不详，甚至词不达意的情况。准确地表达系统难点需要具备如下能力：表达规则和表达工具的熟练性，抽象思维和总结能力的局限性，基础知识体系的完备性，深入浅出的生动表达力。

第1章 编程规约

1.2 常量定义

1.3代码格式

1.4 OOP规约（object-oriented programming ）

1.5 日期时间

1.6 集合处理

1.7 并发处理

1.8 控制语句

1.9 注释规约

1.10 前后端规约

1.11 其他

第2章 异常日志

2.1 错误码

2.2 异常处理

（1）稳定代码示例

（2）非稳定代码示例

（3）不良实践示例（应避免）

2.3 日志规约

1. Maven依赖配置

2. Logback配置文件 (logback.xml)

3. Java代码实现示例

4. 高级配置建议

第3章 单元测试

第4章 安全规约

第5章 MySQL数据库

5.1 建表规约

5.2 索引规约

问题背景理解

原始分页查询的问题

优化方案一：延迟关联

优化原理:先通过索引获取主键ID，然后再关联原表获取完整数据。

优化方案二：子查询优化

优化原理:利用主键或唯一索引的特性，先定位到起始位置，再获取后续记录。

实际案例对比

原始查询（性能差）

优化后的查询（性能好）

其他优化策略

为什么这些优化有效？

5.3 SQL语句

5.4 ORM映射

第6章 工程结构

6.1 应用分层

6.2 二方库依赖

6.3 服务器

第7章 设计规约