Java编程规约

一、 编程规约

(一) 命名风格

1. 【强制】 代码中的命名均不能以 下划线或美元符号 开始，也不能以 下划线或美元符号 结束。

反例：_name / __name / $name / name_ / name$ / name__。

2. 【强制】 所有编程相关的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。 说明： 正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，纯拼音命名方式更要避免采用。

3. 【强制】 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格。

正例： localValue / getHttpMessage() / inputUserId 。

4. 【强制】 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

 正例： MAX_STOCK_COUNT / CACHE_EXPIRED_TIME 。

5. 【强制】 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类

命名以它要测试的类的名称开始，以 Test 结尾。

6. 【强制】 类型与中括号紧挨相连来表示数组。

正例： 定义整形数组 int[] arrayDemo。

反例： 在 main 参数中，使用 String args[]来定义。

7. 【强制】 POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列 化错误。

说明： 在本文 MySQL 规约中的建表约定第一条，表达是与否的变量采用 is_xxx 的命名方式，      所以，需要 在<resultMap>设置从 is_xxx 到 xxx 的映射关系。

8. 【强制】 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用

单数 形式，但是类名如果有复数含义，类名可以使用复数形式。

9. 【推荐】 接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，确定与接口方法相关，并且是整个应用的基础常量。

正例： 接口方法签名 void commit();

正例： 接口基础常量 String COMPANY = "alibaba";

10.接口和实现类的命名规则： 【强制】 对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别。

正例： CacheServiceImpl 实现 CacheService 接口。

11. 【参考】 枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明： 枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例： 枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

(二) 常量定义

1. 【强制】 在 long 或者 Long 赋值时，数值后使用大写字母 L，不能是小写字母 l，小写容易跟

数字混淆，造成误解。

说明： Long a = 2l; 写的是数字的 21，还是 Long 型的 2？

2. 【推荐】 不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

说明： 大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解，也不利于维护。

正例： 缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 SystemConfigConsts 下。

3. 【推荐】 如果变量值仅在一个固定范围内变化用 enum 类型来定义。

说明： 如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表示一年中的第几个季节。

(三) 代码格式

public static void main(String[] args) {
     // 缩进 4 个空格
     String say = "hello";
     // 运算符的左右必须有一个空格
     int flag = 0;
     // 关键词 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格
     if (flag == 0) {
     System.out.println(say);
     }
     // 左大括号前加空格且不换行；左大括号后换行
     if (flag == 1) {
     System.out.println("world");
     // 右大括号前换行，右大括号后有 else，不用换行
     } else {
     System.out.println("ok");
     // 在右大括号后直接结束，则必须换行
     }
}

1. 【强制】 注释的双斜线与注释内容之间有且仅有一个空格。

正例：

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

String commentString = new String ();

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

正例：

double first = 3.2d ;

int second = ( int ) first + 2 ;

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

正例： 下例中实参的 args1 ，后边必须要有一个空格。

method(args1, args2, args3);

(四) OOP 规约

1. 【强制】 避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成

本，直接用 类名 来访问即可。

2. 【强制】 所有的覆写方法，必须加@ Override 注解。

说明： getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。

3. 【强制】 Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用 equals 。

正例： "test".equals(object);

反例： object.equals("test");

4. 【强制】 基本数据类型浮点数不能用==来比较，包装数据类型浮点数不能用 equals 来判断。

说明： 浮点数采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方式。二进 制无法精确表示大部分的十进制小数，具体原理参考 《码出高效》 。

反例：
    float a = 1.0F - 0.9F;
    float b = 0.9F - 0.8F;
    if (a == b) {
     // 预期进入此代码块，执行其它业务逻辑
     // 但事实上 a==b 的结果为 false
    }
    Float x = Float.valueOf(a);
    Float y = Float.valueOf(b);
    if (x.equals(y)) {
     // 预期进入此代码块，执行其它业务逻辑
     // 但事实上 equals 的结果为 false
    }

正例：
(1) 指定一个误差范围，两个浮点数的差值在此范围之内，则认为是相等的。
    float a = 1.0F - 0.9F;
    float b = 0.9F - 0.8F;
    float diff = 1e-6F;
    if (Math.abs(a - b) < diff) {
     System.out.println("true");
    }
(2) 使用 BigDecimal 来定义值，再进行浮点数的运算操作。
    BigDecimal a = new BigDecimal("1.0");
    BigDecimal b = new BigDecimal("0.9");
    BigDecimal c = new BigDecimal("0.8");
    BigDecimal x = a.subtract(b);
    BigDecimal y = b.subtract(c);
    if (x.compareTo(y) == 0) {
     System.out.println("true");
    }

5. 【强制】 如上所示 BigDecimal 的等值比较应使用 compareTo()方法，而不是 equals()方法。

说明： equals()方法会比较值和精度 （1.0 与 1.00 返回结果为 false） ，而 compareTo()则会忽略精度。

6.关于基本数据类型与包装数据类型的使用标准如下：

1） 【强制】 所有的 POJO 类属性必须使用包装数据类型。

2） 【强制】 RPC 方法的返回值和参数必须使用包装数据类型。

3） 【推荐】 所有的局部变量使用基本数据类型。

7. 【强制】 序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败；如果

完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。

说明： 注意 serialVersionUID 不一致会抛出序列化运行时异常。

8. 【强制】 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。

9. 【强制】 POJO 类必须写 toString 方法。使用 IDE 中的工具：source> generate toString

时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。

说明： 在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。

10. 【强制】 禁止在 POJO 类中，同时存在对应属性 xxx 的 isXxx() 和 getXxx() 方法。

11. 【推荐】 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter / setter

方法。

说明： 公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可 能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载 的信息价值较低，所有 Service 和 DAO 的 getter/setter 方法放在类体最后。

12. 【推荐】 慎用 Object 的 clone 方法来拷贝对象。

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

13. 【推荐】 final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字：

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

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

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

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

5） 避免上下文重复使用一个变量，使用 final 关键字可以强制重新定义一个变量，方便更好地进行重构。

14. 【推荐】 类成员与方法访问控制从严：

1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。

2） 工具类不允许有 public 或 default 构造方法。

3） 类非 static 成员变量并且与子类共享，必须是 protected。

4） 类非 static 成员变量并且仅在本类使用，必须是 private。

5） 类 static 成员变量如果仅在本类使用，必须是 private。

6） 若是 static 成员变量，考虑是否为 final。

7） 类成员方法只供类内部调用，必须是 private。

8） 类成员方法只对继承类公开，那么限制为 protected。

(五) 日期时间

1. 【强制】 在日期格式中分清楚大写的 M 和小写的 m，大写的 H 和小写的 h 分别指代的意义。

说明： 日期格式中的这两对字母表意如下：

1） 表示月份是大写的 M；

2） 表示分钟则是小写的 m；

3） 24 小时制的是大写的 H；

4） 12 小时制的则是小写的 h。

2. 【强制】 获取当前毫秒数：System.currentTimeMillis(); 而不是 new Date().getTime()。

说明： 如果想获取更加精确的纳秒级时间值，使用 System.nanoTime 的方式。

3. 【强制】 不要在程序中写死一年为 365 天，避免在公历闰年时出现日期转换错误或程序逻辑

错误。

正例1：表示日期和时间的格式如下所示：
new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")
正例2：
// 获取今年的天数
int daysOfThisYear = LocalDate.now().lengthOfYear();
// 获取指定某年的天数
LocalDate.of(2011, 1, 1).lengthOfYear();

(六) 集合处理

1. 【强制】 关于 hashCode 和 equals 的处理，遵循如下规则：

1） 只要覆写 equals，就必须覆写 hashCode。

2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须覆写 这两种方法。

3） 如果自定义对象作为 Map 的键，那么必须覆写 hashCode 和 equals。

说明： String 因为覆写了 hashCode 和 equals 方法，所以可以愉快地将 String 对象作为 key 来使用。

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

说明： 在某些集合中，前者的时间复杂度为 O(1)，而且可读性更好。

正例：

Map < String , Object > map = new HashMap <> (16);

if ( map . isEmpty ()) {

System . out . println ( "no element in this map." );

}

3. 【强制】 在使用 java.util.stream.Collectors 类的 toMap()方法转为 Map 集合时，一定要使

用含有参数类型为 BinaryOperator，参数名为 mergeFunction 的方法，否则当出现相同 key

值时会抛出 IllegalStateException 异常。

说明： 参数 mergeFunction 的作用是当出现 key 重复时，自定义对 value 的处理策略。

正例：
List<Pair<String, Double>> pairArrayList = new ArrayList<>(3);
pairArrayList.add(new Pair<>("version", 12.10));
pairArrayList.add(new Pair<>("version", 12.19));
pairArrayList.add(new Pair<>("version", 6.28));
Map<String, Double> map = pairArrayList.stream().collect(
// 生成的 map 集合中只有一个键值对：{version=6.28}
Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2));
反例：
String[] departments = new String[] {"iERP", "iERP", "EIBU"};
// 抛出 IllegalStateException 异常
Map<Integer, String> map = Arrays.stream(departments)
 .collect(Collectors.toMap(String::hashCode, str -> str));

4. 【强制】 在使用 java.util.stream.Collectors 类的 toMap()方法转为 Map 集合时，一定要注

意当 value 为 null 时会抛 NPE 异常。

说明： 在 java.util.HashMap 的 merge 方法里会进行如下的判断：

正例：
if (value == null || remappingFunction == null)
throw new NullPointerException();
反例：
List<Pair<String, Double>> pairArrayList = new ArrayList<>(2);
pairArrayList.add(new Pair<>("version1", 8.3));
pairArrayList.add(new Pair<>("version2", null));
Map<String, Double> map = pairArrayList.stream().collect(
// 抛出 NullPointerException 异常
Collectors.toMap(Pair::getKey, Pair::getValue, (v1, v2) -> v2));

5. 【强制】 使用 Map 的方法 keySet() / values() / entrySet() 返回集合对象时，不可以对其进行添

加元素操作，否则会抛出 UnsupportedOperationException 异常。

6. 【强制】 使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一

致、长度为 0 的空数组。

反例： 直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[] 类，若强转其它类型数组将出现 ClassCastException 错误。

正例：

List < String > list = new ArrayList <> ( 2 );

list . add ( "guan" );

list . add ( "bao" );

String [] array = list . toArray ( new String [ 0 ]);

说明： 使用 toArray 带参方法，数组空间大小的 length ：

1 ） 等于 0 ，动态创建与 size 相同的数组，性能最好。

2 ） 大于 0 但小于 size ，重新创建大小等于 size 的数组，增加 GC 负担。

3 ） 等于 size ，在高并发情况下，数组创建完成之后， size 正在变大的情况下，负面影响与 2 相同。

4 ） 大于 size ，空间浪费，且在 size 处插入 null 值，存在 NPE 隐患。

7. 【强制】 使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，

它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。

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

8. 【强制】 泛型通配符 <? extends T> 来接收返回的数据，此写法的泛型集合不能使用 add 方法，

而 <? super T> 不能使用 get 方法，两者在接口调用赋值的场景中容易出错。

说明： 扩展说一下 PECS(Producer Extends Consumer Super)原则：第一、频繁往外读取内容的，适合用 <? extends T>。第二、经常往里插入的，适合用<? super T>

9. 【强制】 不要在 foreach 循环里进行元素的 remove/add 操作。remove 元素请使用 Iterator

方式，如果并发操作，需要对 Iterator 对象加锁。

正例：
List<String> list = new ArrayList<>();
list.add("1");
list.add("2");
Iterator<String> iterator = list.iterator();
while (iterator.hasNext()) {
 String item = iterator.next();
 if (删除元素的条件) {
 iterator.remove();
 }
}
反例：
for (String item : list) {
 if ("1".equals(item)) {
 list.remove(item);
 }
}

10. 【推荐】 使用 entrySet 遍历 Map 类集合 KV ，而不是 keySet 方式进行遍历。

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

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

11. 【参考】 利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的

contains()进行遍历去重或者判断包含操作.

(七) 并发处理

1. 【强制】 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。

说明： 资源驱动类、工具类、单例工厂类都需要注意。

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

说明： 线程池的好处是减少在创建和销毁线程上所消耗的时间以及系统资源的开销，解决资源不足的问题。 如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过度切换”的问题。

3. 【强制】 线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这

样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。

说明： Executors 返回的线程池对象的弊端如下：

1） FixedThreadPool 和 SingleThreadPool ：

允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。

2） CachedThreadPool ：

允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。

4. 【强制】 必须回收自定义的 ThreadLocal 变量，尤其在线程池场景下，线程经常会被复用，

如果不清理自定义的 ThreadLocal 变量，可能会影响后续业务逻辑和造成内存泄露等问题。

尽量在代理中使用 try-finally 块进行回收。

正例：

objectThreadLocal . set ( userInfo );

try {

// ...

} finally {

objectThreadLocal . remove ();

}

5. 【强制】 高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁 ； 能

锁区块，就不要锁整个方法体 ； 能用对象锁，就不要用类锁。

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

6. 【强制】 对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造

成死锁。

说明： 线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是 A、 B、C，否则可能出现死锁。

7. 【强制】 在使用阻塞等待获取锁的方式中，必须在 try 代码块之外，并且在加锁方法与 try 代

码块之间没有任何可能抛出异常的方法调用，避免加锁成功后，在 finally 中无法解锁。

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

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

IllegalMonitorStateException 异常。

说明三： 在 Lock 对象的 lock 方法实现中可能抛出 unchecked 异常，产生的后果与说明二相同。

正例：
Lock lock = new XxxLock();
// ...
lock.lock();
try {
 doSomething();
 doOthers();
} finally {
 lock.unlock();
}
反例：
Lock lock = new XxxLock();
// ...
try {
 // 如果此处抛出异常，则直接执行 finally 代码块
 doSomething();
 // 无论加锁是否成功，finally 代码块都会执行
 lock.lock();
 doOthers();
} finally {
 lock.unlock();
}

10. 【强制】 在使用尝试机制来获取锁的方式中，进入业务代码块之前，必须先判断当前线程是否

持有锁。锁的释放规则与锁的阻塞等待方式相同。

说明： Lock 对象的 unlock 方法在执行时，它会调用 AQS 的 tryRelease 方法（取决于具体实现类），如果 当前线程不持有锁，则抛出 IllegalMonitorStateException 异常。

正例：

Lock lock = new XxxLock ();

// ...

boolean isLocked = lock . tryLock ();

if ( isLocked ) {

        try {

                doSomething ();

                doOthers ();

         } finally {

                lock . unlock ();

        }

}

11. 【强制】 并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加

锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。

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

3 次。

12. 【参考】 volatile 解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但

是如果多写，同样无法解决线程安全问题。

说明： 如果是 count++操作，使用如下类实现：AtomicInteger count = new AtomicInteger();

count.addAndGet(1); 如果是 JDK8，推荐使用 LongAdder 对象，比 AtomicLong 性能更好（减少乐观 锁的重试次数）

13. 【参考】 HashMap 在容量不够进行 resize 时由于高并发可能出现死链，导致 CPU 飙升，在

开发过程中注意规避此风险。

14. 【参考】 ThreadLocal 对象使用 static 修饰，ThreadLocal 无法解决共享对象的更新问题。

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

(八) 控制语句

1. 【强制】 在一个 switch 块内，每个 case 要么通过 continue/break/return 等来终止，要么

注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default

语句并且放在最后，即使它什么代码也没有。

说明： 注意 break 是退出 switch 语句块，而 return 是退出方法 体。

2. 【强制】 当 switch 括号内的变量类型为 String 并且此变量为外部参数时，必须先进行 null

判断。

反例：如下的代码输出是什么？
public class SwitchString {
 public static void main(String[] args) {
     method(null);
 }
 public static void method(String param) {
     switch (param) {
     // 肯定不是进入这里
     case "sth":
         System.out.println("it's sth");
         break;
     // 也不是进入这里
     case "null":
         System.out.println("it's null");
         break;
     // 也不是进入这里
     default:
         System.out.println("default");
     }
 }
}

3. 【强制】 三目运算符 condition? 表达式 1 : 表达式 2 中，高度注意表达式 1 和 2 在类型对齐

时，可能抛出因自动拆箱导致的 NPE 异常。

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

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

2） 表达式 1 或表达式 2 的值的类型不一致，会强制拆箱升级成表示范围更大的那个类型。

反例：

Integer a = 1 ;

Integer b = 2 ;

Integer c = null ;

Boolean flag = false ;

// a*b 的结果是 int 类型，那么 c 会强制拆箱成 int 类型，抛出 NPE 异常

Integer result = ( flag ? a * b : c );

5. 【强制】 在高并发场景中，避免使用”等于”判断作为中断或退出的条件。

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

反例： 判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数， 这样的话，活动无法终止。

6. 【推荐】 表达异常的分支时，少用 if-else 方式 ，这种方式可以改写成：

if ( condition ) {

...

return obj ;

}

正例： 超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，其中卫语句

示例如下：

public void findBoyfriend ( Man man ) {

        if ( man . isUgly ()) {

                System . out . println ( "本姑娘是外貌协会的资深会员" );

                return ;

        }

        if ( man . isPoor ()) {

                System . out . println ( "贫贱夫妻百事哀" );

                return ;

        }

        if ( man . isBadTemper ()) {

                System . out . println ( "银河有多远，你就给我滚多远" );

                return ;

        }

        System . out . println ( "可以先交往一段时间看看" );

}

7. 【推荐】 避免采用取反逻辑运算符。

说明： 取反逻辑不利于快速理解，并且取反逻辑写法一般都存在对应的正向逻辑写法。

正例： 使用 if (x < 628) 来表达 x 小于 628。

反例： 使用 if (!(x >= 628)) 来表达 x 小于 628。

8. 【推荐】 公开接口需要进行入参保护，尤其是批量操作的接口。

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

(九) 注释规约

1. 【强制】 类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用

// xxx 方式。

说明： 在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

2. 【强制】 所有的抽象方法 （ 包括接口中的方法 ） 必须要用 Javadoc 注释、除了返回值、参数、

异常说明外，还必须指出该方法做什么事情，实现什么功能。

说明： 对子类的实现要求，或者调用注意事项，请一并说明

3. 【强制】 所有的类都必须添加创建者和创建日期。

说明： 在设置模板时，注意 IDEA 的@author 为`${USER}`，而 eclipse 的@author 为`${user}`，大小写有区别，而日期的设置统一为 yyyy/MM/dd 的格式 。

正例：

/**

* @author yangguanbao

* @date 2016/10/31

*/

4. 【强制】 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使

用/* */注释，注意与代码对齐。

5. 【强制】 所有的枚举类型字段必须要有注释，说明每个数据项的用途。

6. 【参考】 对于注释的要求：第一、能够准确反映设计思想和代码逻辑 ； 第二、能够描述业务含

义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同

天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路 ； 注释也是给继任者看

的，使其能够快速接替自己的工作。

7. 【参考】 谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

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

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

2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。

(十) 前后端规约

1. 【强制】 前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响

应体。

说明：

1） 协议：生产环境必须使用 HTTPS。

2） 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：

        a） 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。

        b） URL 路径不能使用大写，单词如果需要分隔，统一使用下划线。

        c） 路径禁止携带表示请求内容类型的后缀，比如".json",".xml"，通过 accept 头表达即可。

3） 请求方法：对具体操作的定义，常见的请求方法如下：

        a） GET：从服务器取出资源。

        b） POST：在服务器新建一个资源。

        c） PUT：在服务器更新资源。

        d） DELETE：从服务器删除资源。

4） 请求内容：URL 带的参数必须无敏感信息或符合安全要求；body 里带参数时必须设置 Content-Type。

5） 响应体：响应体 body 可放置多种数据类型，由 Content-Type 头来确定。

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

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

3. 【强制】 服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码.

正例： 常见的 HTTP 状态码如下

1） 200 OK: 表明该请求被成功地完成，所请求的资源发送到客户端。

2） 401 Unauthorized: 请求要求身份验证，常见对于需要登录而用户未登录的情况。

3） 403 Forbidden：服务器拒绝请求，常见于机密信息或复制其它登录用户链接访问服务器的情况。

4） 404 Not Found: 服务器无法取得所请求的网页，请求资源不存在。

5） 500 Internal Server Error: 服务器内部错误。

4. 【强制】 HTTP 请求通过 body 传递内容时，必须控制长度，超出最大长度后，后端解析会出

错。

说明： nginx 默认限制是 1MB，tomcat 默认限制为 2MB，当确实有业务需要传较大内容时，可以通过调 大服务器端的限制。

5. 【强制】 在翻页场景中，用户输入参数的小于 1，则前端返回第一页参数给后端；后端发现用

户输入的参数大于总页数，直接返回最后一页。

6. 【强制】 服务器内部重定向必须使用 forward；外部重定向地址必须使用 URL 统一代理模块

生成，否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”，并且还会带来 URL 维护

不一致的问题。

7. 【推荐】 服务端返回的数据，使用 JSON 格式而非 XML。

说明： 尽管 HTTP 支持使用不同的输出格式，例如纯文本，JSON，CSV，XML，RSS 甚至 HTML。如果我

们使用的面向用户的服务，应该选择 JSON 作为通信中使用的标准数据交换格式，包括请求和响应。此外，

application/JSON 是一种通用的 MIME 类型，具有实用、精简、易读的特点。

8. 【推荐】 前后端的时间格式统一为"yyyy-MM-dd HH:mm:ss"，统一为 GMT。

(十一) 其他

1. 【强制】 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。

说明： 不要在方法体内定义：Pattern pattern = Pattern.compile(“规则”);

2. 【强制】 避免用 Apache Beanutils 进行属性的 copy。

说明： Apache BeanUtils 性能较差，可以使用其他方案比如 Spring BeanUtils, Cglib BeanCopier，注意均是浅拷贝。

3. 【强制】 velocity 调用 POJO 类的属性时，直接使用属性名取值即可，模板引擎会自动按规范

调用 POJO 的 getXxx() ，如果是 boolean 基本数据类型变量 （boolean 命名不需要加 is 前缀 ） ，

会自动调用 isXxx() 方法。

说明： 注意如果是 Boolean 包装类对象，优先调用 getXxx()的方法。

4. 【强制】 后台输送给页面的变量必须加 $!{var} ——中间的感叹号。

说明： 如果 var 等于 null 或者不存在，那么${var}会直接显示在页面上。

5. 【强制】 注意 Math . random() 这个方法返回是 double 类型，注意取值的范围 0≤ x <1 （ 能够

取到 零 值，注意除零异常 ） ，如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后

取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法。

6. 【推荐】 任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。

7. 【推荐】 及时清理不再使用的代码段或配置信息。

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

正例： 对于暂时被注释掉，后续可能恢复使用的代码片断，在注释代码上方，统一规定使用三个斜杠(///) 来说明注释掉代码的理由。如：

public static void hello () {

/// 业务方通知活动暂停

// Business business = new Business();

// business.active();

System . out . println ( "it's finished" );

}

二、异常日志 

(一) 错误码

1. 【强制】 错误码的制定原则：快速溯源、沟通标准化。

说明： 错误码想得过于完美和复杂，就像康熙字典中的生僻字一样，用词似乎精准，但是字典不容易随身 携带并且简单易懂。

正例： 错误码回答的问题是谁的错？错在哪？

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

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

3）错误码有利于团队快速对错误原因达到一致认知。

2. 【强制】 错误码不体现版本号和错误等级信息。

说明： 错误码以不断追加的方式进行兼容。错误等级由日志和错误码本身的释义来决定。

3. 【强制】 全部正常，但不得不填充错误码时返回五个零：00000。

4. 【强制】 错误码为字符串类型，共 5 位，分成两个部分：错误产生来源+四位数字编号。

5. 【强制】 错误码不能直接输出给用户作为提示信息使用。

说明： 堆栈（stack_trace）、错误信息(error_message)、错误码（error_code）、提示信息（user_tip）是一个有效关联并互相转义的和谐整体，但是请勿互相越俎代庖。

6. 【推荐】 错误码之外的业务独特信息由 error_message 来承载，而不是让错误码本身涵盖过

多具体业务属性.

7. 【参考】 错误码的后三位编号与 HTTP 状态码没有任何关系。

8. 【参考】 错误码即人性，感性认知+口口相传，使用纯数字来进行错误码编排不利于感性记忆

和分类。

说明： 数字是一个整体，每位数字的地位和含义是相同的。

反例： 一个五位数字 12345，第 1 位是错误等级，第 2 位是错误来源，345 是编号，人的大脑不会主动地拆开并分辨每位数字的不同含义。

(二) 异常处理

1. 【强制】 Java 类库中定义的可以通过预检查方式规避的 RuntimeException 异常不应该通过

catch 的方式来处理，比如： NullPointerException ， IndexOutOfBoundsException 等等。

说明： 无法通过预检查的异常除外，比如，在解析字符串形式的数字时，可能存在数字格式错误，不得不通过 catch NumberFormatException 来实现。

正例： if (obj != null) {...}

反例： try { obj.method(); } catch (NullPointerException e) {…}

2. 【强制】 异常 捕获后 不要用来做流程控制，条件控制。

说明： 异常设计的初衷是解决程序运行中的各种意外情况，且异常的处理效率比条件判断方式要低很多。

3. 【强制】 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请

将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的

内容。

4. 【强制】 事务场景中，抛出异常被 catch 后，如果需要回滚，一定要注意手动回滚事务。

5. 【强制】 finally 块必须对资源对象、流对象进行关闭，有异常也要做 try-catch。

说明： 如果 JDK7 及以上，可以使用 try-with-resources 方式。

6. 【强制】 不要在 finally 块中使用 return 。

说明： try 块中的 return 语句执行成功后，并不马上返回，而是继续执行 finally 块中的语句，如果此处存在 return 语句，则在此直接返回，无情丢弃掉 try 块中的返回点。

反例：

private int x = 0 ;

public int checkReturn () {

        try {

        // x 等于 1，此处不返回

                return ++ x ;

        } finally {

        // 返回的结果是 2

                return ++ x ;

        }

}

8. 【强制】 捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。

说明： 如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

9. 【推荐】 防止 NPE ，是程序员的基本修养，注意 NPE 产生的场景：

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。

正例： 使用 JDK8 的 Optional 类来防止 NPE 问题

(三) 日志规约

1. 【强制】 应用中不可直接使用日志系统 （Log 4 j 、 Logback） 中的 API ，而应依赖使用日志框架

（SLF4J、JCL--Jakarta Commons Logging） 中的 API ，使用门面模式的日志框架，有利于维护和 各个类的日志处理方式统一。

说明： 日志框架（SLF4J、JCL--Jakarta Commons Logging）的使用方式（推荐使用 SLF4J）

使用 SLF4J：

import org . slf4j . Logger ;

import org . slf4j . LoggerFactory ;

private static final Logger logger = LoggerFactory . getLogger ( Test . class );

使用 JCL：

import org . apache . commons . logging . Log ;

import org . apache . commons . logging . LogFactory ;

private static final Log log = LogFactory . getLog ( Test . class );

2. 【强制】 所有日志文件至少保存 15 天，因为有些异常具备以“周”为频次发生的特点。对于

当天日志，以“应用名.log”来保存，保存在/home/admin/应用名/logs/目录下，过往日志

格式为: {logname}.log.{保存日期}，日期格式：yyyy-MM-dd

正例： 以 aap 应用为例，日志保存在/home/admin/aapserver/logs/aap.log，历史日志名称为

aap.log.2016-08-01

5. 【强制】 在日志输出时，字符串变量之间的拼接使用占位符的方式。

说明： 因为 String 字符串的拼接会使用 StringBuilder 的 append() 方式，有一定的性能损耗。使用占位符仅 是替换动作，可以有效提升性能。

正例： logger . debug ( "Processing trade with id: {} and symbol: {}" , id , symbol );

6. 【强制】 对于 trace / debug / info 级别的日志输出，必须进行日志级别的开关判断。

说明： 虽然在 debug( 参数 ) 的方法体内第一行代码 isDisabled(Level.DEBUG_INT) 为真时（ Slf4j 的常见实现 Log4j 和 Logback ），就直接 return ，但是参数可能会进行字符串拼接运算。此外，如果 debug(getName()) 这种参数内有 getName() 方法调用，无谓浪费方法调用的开销。

正例：

// 如果判断为真，那么可以输出 trace 和 debug 级别的日志

if ( logger . isDebugEnabled ()) {

logger . debug ( "Current ID is: {} and name is: {}" , id , getName ());

}

7. 【推荐】 谨慎地记录日志。生产环境禁止输出 debug 日志 ； 有选择地输出 info 日志 ； 如果使用

warn 来记录刚上线时的业务行为信息，一定要注意日志输出量的问题，避免把服务器磁盘撑

爆，并记得及时删除这些观察日志。

说明： 大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。记录日志时请思考：这些 日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？

8. 【推荐】 可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适

从。如非必要，请不要在此场景打出 error 级别，避免频繁报警。

说明： 注意日志输出的级别，error 级别只记录系统逻辑出错、异常或者重要的错误信息。

三、单元测试

1. 【强制】 好的单元测试必须遵守 AIR 原则。

说明： 单元测试在线上运行时，感觉像空气（AIR）一样感觉不到，但在测试质量的保障上，却是非常关键

的。好的单元测试宏观上来说，具有自动化、独立性、可重复执行的特点。

  A ：Automatic（自动化）

  I ：Independent（独立性）

  R ：Repeatable（可重复）

2. 【强制】 单元测试应该是全自动执行的，并且非交互式的。测试用例通常是被定期执行的，执

行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元

测试中不准使用 System.out 来进行人肉验证，必须使用 assert 来验证。

3. 【强制】 对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单测粒度至多是类级

别，一般是方法级别。

说明： 只有测试粒度小才能在出错时尽快定位到出错位置。单测不负责检查跨类或者跨系统的交互逻辑，那是集成测试的领域

4. 【强制】 核心业务、核心应用、核心模块的增量代码确保单元测试通过。

说明： 新增代码及时补充单元测试，如果新增代码影响了原有单元测试，请及时修正。

5. 【强制】 单元测试代码必须写在如下工程目录： src/test/java ，不允许写在业务代码目录下。

说明： 源码编译时会跳过此目录，而单元测试框架默认是扫描此目录。

6. 【推荐】 单元测试的基本目标：语句覆盖率达到 70% ；核心模块的语句覆盖率和分支覆盖率都

要达到 100%

说明： 在工程规约的应用分层中提到的 DAO 层，Manager 层，可重用度高的 Service，都应该进行单元测 试。

7. 【推荐】 编写单元测试代码遵守 BCDE 原则，以保证被测试模块的交付质量。

  B ：Border，边界值测试，包括循环边界、特殊取值、特殊时间点、数据顺序等。

  C ：Correct，正确的输入，并得到预期的结果。

  D ：Design，与设计文档相结合，来编写单元测试。

  E ：Error，强制错误信息输入（如：非法数据、异常流程、业务允许外等），并得到预期的结果。

8. 【推荐】 单元测试作为一种质量保障手段，在项目提测前完成单元测试，不建议项目发布后补

充单元测试用例。

四、安全规约

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

说明： 防止没有做水平权限校验就可随意访问、修改、删除别人的数据，比如查看他人的私信内容。

2. 【强制】 用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

说明： 中国大陆个人手机号码显示：139****1219，隐藏中间 4 位，防止隐私泄露。

3. 【强制】 用户输入的 SQL 参数严格使用参数绑定或者 METADATA 字段值限定，防止 SQL 注入， 禁止字符串拼接 SQL 访问数据库。

反例： 某系统签名大量被恶意修改，即是因为对于危险字符 # --没有进行转义，导致数据库更新时，where 后边的信息被注释掉，对全库进行更新。

4. 【强制】 用户请求传入的任何参数必须做有效性验证。

说明： 忽略参数校验可能导致：

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

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

 3） 缓存击穿

 4） SSRF

 5） 任意重定向

 6） SQL 注入，Shell 注入，反序列化注入

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

Java 代码用正则来验证客户端的输入，有些正则写法验证普通用户输入没有问题，但是如果攻击人员使用 的是特殊构造的字符串来验证，有可能导致死循环的结果。

5. 【强制】 禁止向 HTML 页面输出未经安全过滤或未正确转义的用户数据。

6. 【强制】 表单、 AJAX 提交必须执行 CSRF 安全验证。

说明： CSRF(Cross-site request forgery)跨站请求伪造是一类常见编程漏洞。对于存在 CSRF 漏洞的应用/ 网站，攻击者可以事先构造好 URL，只要受害者用户一访问，后台便在用户不知情的情况下对数据库中用 户参数进行相应修改。

7. 【强制】 URL 外部重定向传入的目标地址必须执行白名单过滤。

8. 【强制】 在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放的机

制，如数量限制、疲劳度控制、验证码校验，避免被滥刷而导致资损。

说明： 如注册时发送验证码到手机，如果没有限制次数和频率，那么可以利用此功能骚扰到其它用户，并 造成短信平台资源浪费。

9. 【推荐】 发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过

滤等风控策略

五、MySQL 数据库

(一) 建表规约

1. 【强制】 表达是与否概念的字段，必须使用 is_xxx 的方式命名，数据类型是 unsigned tinyint

（1 表示是，0 表示否）。

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

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

正例： 表达逻辑删除的字段名 is_deleted ，1 表示删除，0 表示未删除。

2. 【强制】 表名、字段名必须使用小写字母或数字 ， 禁止出现数字开头，禁止两个下划线中间只

出现数字。数据库字段名的修改代价很大，因为无法进行预发布，所以字段名称需要慎重考虑。

说明： MySQL 在 Windows 下不区分大小写，但在 Linux 下默认是区分大小写。因此，数据库名、表名、字段名，都不允许出现任何大写字母，避免节外生枝。

正例： aliyun_admin，rdc_config，level3_name

反例： AliyunAdmin，rdcConfig，level_3_name

3. 【强制】 表名不使用复数名词。

说明： 表名应该仅仅表示表里面的实体内容，不应该表示实体数量，对应于 DO 类名也是单数形式，符合表达习惯。

4. 【强制】 主键索引名为 pk_ 字段名；唯一索引名为 uk _字段名 ； 普通索引名则为 idx _字段名。

说明： pk_ 即 primary key；uk_ 即 unique key；idx_ 即 index 的简称。

5. 【强制】 小数类型为 decimal，禁止使用 float 和 double。

说明： 在存储的时候，float 和 double 都存在精度损失的问题，很可能在比较值的时候，得到不正确的结果。如果存储的数据范围超过 decimal 的范围，建议将数据拆成整数和小数并分开存储。

6. 【强制】 varchar 是可变长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度

大于此值，定义字段类型为 text ，独立出来一张表，用主键来对应，避免影响其它字段索引效

率。

7. 【强制】 表必备三字段：id, create_time, update_time。

说明： 其中 id 必为主键，类型为 bigint unsigned、单表时自增、步长为 1。create_time, update_time 的类型均为 datetime 类型，前者现在时表示主动式创建，后者过去分词表示被动式更新

(二) 索引规约

1. 【强制】 业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。

说明： 不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速度是明显的；另外，即使在应用层做了非常完善的校验控制，只要没有唯一索引，根据墨菲定律，必然有脏数据产生。

2. 【强制】 超过三个表禁止 join 。需要 join 的字段，数据类型保持绝对一致 ； 多表关联查询时，

保证被关联的字段需要有索引。

说明： 即使双表 join 也要注意表索引、SQL 性能。

3. 【强制】 在 varchar 字段上建立索引时，必须指定索引长度，没必要对全字段建立索引，根据

实际文本区分度决定索引长度。

说明： 索引的长度与区分度是一对矛盾体，一般对字符串类型数据，长度为 20 的索引，区分度会高达 90% 以上，可以使用 count(distinct left(列名, 索引长度))/count(*)的区分度来确定。

4. 【强制】 页面搜索严禁左模糊或者全模糊，如果需要请走搜索引擎来解决。

说明： 索引文件具有 B-Tree 的最左前缀匹配特性，如果左边的值未确定，那么无法使用此索引。

5. 【推荐】 如果有 order by 的场景，请注意利用索引的有序性。order by 最后的字段是组合索

引的一部分，并且放在索引组合顺序的最后，避免出现 file_sort 的情况，影响查询性能。

正例： where a=? and b=? order by c; 索引：a_b_c

反例： 索引如果存在范围查询，那么索引有序性无法利用，如：WHERE a>10 ORDER BY b; 索引 a_b 无 法排序。

6. 【推荐】 利用覆盖索引来进行查询操作，避免回表。

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

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

7. 【推荐】 利用延迟关联或者子查询优化超多分页场景。

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

改写。

正例： 先快速定位需要获取的 id 段，然后再关联：

SELECT t1.* FROM 表 1 as t1, (select id from 表 1 where 条件 LIMIT 100000,20 ) as t2 where t1.id=t2.id

8. 【推荐】 建组合索引的时候，区分度最高的在最左边。

正例： 如果 where a=? and b=?，a 列的几乎接近于唯一值，那么只需要单建 idx_a 索引即可。

说明： 存在非等号和等号混合判断条件时，在建索引时，请把等号条件的列前置。

如：where c>? and d=? 那么即使 c 的区分度更高，也必须把 d 放在索引的最前列，即建立组合索引 idx_d_c。

(三) SQL 语句

1. 【强制】 不要使用 count(列名)或 count(常量)来替代 count(*)，count(*)是 SQL92 定义的标

准统计行数的语法，跟数据库无关，跟 NULL 和非 NULL 无关。

说明： count(*)会统计值为 NULL 的行，而 count(列名)不会统计此列为 NULL 值的行。

2. 【强制】 count(distinct col) 计算该列除 NULL 之外的不重复行数，注意 count(distinct col1,

col2) 如果其中一列全为 NULL，那么即使另一列有不同的值，也返回为 0。

3. 【强制】 当某一列的值全是 NULL 时，count(col)的返回结果为 0，但 sum(col)的返回结果为

NULL，因此使用 sum()时需注意 NPE 问题。

正例： 可以使用如下方式来避免 sum 的 NPE 问题：SELECT IFNULL(SUM(column), 0) FROM table;

4. 【强制】 使用 ISNULL() 来判断是否为 NULL 值。

说明： NULL 与任何值的直接比较都为 NULL 。

1） NULL<>NULL 的返回结果是 NULL ，而不是 false 。

2） NULL=NULL 的返回结果是 NULL ，而不是 true 。

3） NULL<>1 的返回结果是 NULL ，而不是 true 。

反例： 在 SQL 语句中，如果在 null 前换行，影响可读性。select * from table where column1 is null and column3 is not null; 而`ISNULL(column)`是一个整体，简洁易懂。从性能数据上分析，`ISNULL(column)` 执行效率更快一些。

5. 【强制】 代码中写分页查询逻辑时，若 count 为 0 应直接返回，避免执行后面的分页语句。

6. 【推荐】 SQL 语句中表的别名前加 as，并且以 t1、t2、t3、...的顺序依次命名。

说明：

1）别名可以是表的简称，或者是依照表在 SQL 语句中出现的顺序，以 t1、t2、t3 的方式命名。2） 别名前加 as 使别名更容易识别。

正例： select t1.name from table_first as t1, table_second as t2 where t1.id=t2.id;

7. 【推荐】 in 操作能避免则避免，若实在避免不了，需要仔细评估 in 后边的集合元素数量，控

制在 1000 个之内。

8. 【参考】 TRUNCATE TABLE 比 DELETE 速度快，且使用的系统和事务日志资源少，但 TRUNCATE无事务且不触发 trigger ，有可能造成事故，故不建议在开发代码中使用此语句。

说明： TRUNCATE TABLE 在功能上与不带 WHERE 子句的 DELETE 语句相同。

(四) ORM 映射

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

说明：

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

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

3）无用字段增加网络消耗，尤其是 text 类型的字段。

2. 【强制】 POJO 类的布尔属性不能加 is，而数据库字段必须加 is_，要求在 resultMap 中进行

字段与属性之间的映射。

说明： 参见定义 POJO 类以及数据库字段定义规定，在 sql.xml 增加映射，是必须的。

3. 【强制】 不要用 resultClass 当返回参数，即使所有类属性名与数据库字段一一对应，也需要

定义<resultMap>；反过来，每一个表也必然有一个<resultMap>与之对应。

说明： 配置映射关系，使字段与 DO 类解耦，方便维护。

4. 【强制】 sql. xml 配置参数使用：#{}，# param # 不要使用${} 此种方式容易出现 SQL 注入。

5. 【强制】 iBATIS 自带的 queryForList(String statementName , int start , int size) 不推荐使用。

说明： 其实现方式是在数据库取到 statementName 对应的 SQL 语句的所有记录，再通过 subList 取 start,size 的子集合。

正例：

Map < String , Object > map = new HashMap <> (16);

map . put ( "start" , start );

map . put ( "size" , size );

6. 【强制】 更新数据表记录时，必须同时更新记录对应的 update_time 字段值为当前时间。

7. 【推荐】 不要写一个大而全的数据更新接口。传入为 POJO 类，不管是不是自己的目标更新字

段，都进行 update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行 SQL 时， 不要更新无改动的字段，一是易出错；二是效率低；三是增加 binlog 存储。

8. 【参考】 @Transactional 事务不要滥用。事务会影响数据库的 QPS，另外使用事务的地方需

要考虑各方面的回滚方案，包括缓存回滚、搜索引擎回滚、消息补偿、统计修正等。

六、工程结构

(一) 应用分层

1. 【推荐】 根据业务架构实践，结合业界分层规范与流行技术框架分析，推荐分层结构如图所示，

默认上层依赖于下层，箭头关系表示可直接依赖，如：开放 API 层可以依赖于 Web 层 （Controller 层），也可以直接依赖于 Service 层，依此类推：

• 开放 API 层：可直接封装 Service 接口暴露成 RPC 接口；通过 Web 封装成 http 接口；网关控制层等。

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

• Web 层：主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。

• Service 层：相对具体的业务逻辑服务层。

• Manager 层：通用业务处理层，它有如下特征：

  1） 对第三方平台封装的层，预处理返回结果及转化异常信息，适配上层接口。

  2） 对 Service 层通用能力的下沉，如缓存方案、中间件通用处理。

  3） 与 DAO 层交互，对多个 DAO 的组合复用。

• DAO 层：数据访问层，与底层 MySQL、Oracle、Hbase、OB 等进行数据交互。

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

• 外部数据接口：外部（应用）数据存储服务提供的接口，多见于数据迁移场景中

2. 【参考】 分层领域模型规约：

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

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

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

• Query：数据查询对象，各层接收上层的查询请求。注意超过 2 个参数的查询封装，禁止使用 Map 类来传输。

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

(二) 二方库依赖

1. 【强制】 定义 GAV 遵从以下规则：

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

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

正例： com.taobao.jstorm 或 com.alibaba.dubbo.register

2） A rtifactID 格式：产品线名-模块名。语义不重复不遗漏，先到中央仓库去查证一下。

正例： dubbo-client / fastjson-api / jstorm-tool

3） V ersion：详细规定参考特定文档。

2. 【强制】 二方库版本号命名方式：主版本号.次版本号.修订号

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

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

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

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

反例： 仓库内某二方库版本号从 1.0.0.0 开始，一直默默“升级”成 1.0.0.64，完全失去版本的语义信息。

(三) 服务器  

1. 【推荐】 高并发服务器建议调小 TCP 协议的 time _ wait 超时时间。

说明： 操作系统默认 240 秒后，才会关闭处于 time_wait 状态的连接，在高并发访问下，服务器端会因为 处于 time_wait 的连接数太多，可能无法建立新的连接，所以需要在服务器上调小此等待值。

正例： 在 linux 服务器上请通过变更/etc/sysctl.conf 文件去修改该缺省值（秒）：

net.ipv4.tcp_fin_timeout = 30

2. 【推荐】 给 JVM 环境参数设置 -XX:+HeapDumpOnOutOfMemoryError 参数，让 JVM 碰到 OOM场景时输出 dump 信息。

说明： OOM 的发生是有概率的，甚至相隔数月才出现一例，出错时的堆内信息对解决问题非常有帮助。

3. 【参考】 服务器内部重定向必须使用 forward； 外部重定向地址必须使用 URL Broker 生成，否

则因线上采用 HTTPS 协议而导致浏览器提示“不安全“。此外，还会带来 URL 维护不一致的

问题。

七、设计规约

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

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

正例： 评审内容包括存储介质选型、表结构设计能否满足技术方案、存取性能和存储空间能否满足业务发 展、表或字 段之间的辩证关系、字段名称、字段类型、索引等；数据结构变更（如在原有表中新增字段） 也需要进行评审通过后上线。

2. 【强制】 在需求分析阶段，如果与系统交互的 User 超过 一类 并且相关的 User Case 超过 5 个 ，使用用例图来表达更加清晰的结构化需求。

3. 【强制】 如果某个业务对象的状态超过 3 个 ，使用状态图来表达并且明确状态变化的各个触发

条件。

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

正例： 淘宝订单状态有已下单、待付款、已付款、待发货、已发货、已收货等。比如已下单与已收货这两种状态之间是不可能有直接转换关系的。

4. 【强制】 如果系统中某个功能的调用链路上的涉及对象超过 3 个 ，使用时序图来表达并且明确

各调用环节的输入与输出。

说明： 时序图反映了一系列对象间的交互与协作关系，清晰立体地反映系统的调用纵深链路。

5. 【强制】 如果系统中模型类超过 5 个 ，并且存在复杂的依赖关系，使用类图来表达并且明确类

之间的关系。

说明： 类图像建筑领域的施工图，如果搭平房，可能不需要，但如果建造蚂蚁 Z 空间大楼，肯定需要详细的施工图。

6. 【强制】 如果系统中超过 2 个 对象之间存在协作关系，并且需要表示复杂的处理流程，使用活

动图来表示。

说明： 活动图是流程图的扩展，增加了能够体现协作关系的对象泳道，支持表示并发等。

7. 【推荐】 系统架构设计时明确以下目标：

 1） 确定系统边界。确定系统在技术层面上的做与不做。

 2） 确定系统内模块之间的关系。确定模块之间的依赖关系及模块的宏观输入与输出。

 3） 确定指导后续设计与演化的原则。使后续的子系统或模块设计在一个既定的框架内和技术方向上继续演化。

4）确定非功能性需求。非功能性需求是指安全性、可用性、可扩展性等。

8. 【推荐】 需求分析与系统设计在考虑主干功能的同时，需要充分评估异常流程与业务边界。

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

9. 【推荐】 类在设计与实现时要符合单一原则。

说明： 单一原则最易理解却是最难实现的一条规则，随着系统演进，很多时候，忘记了类设计的初衷。

10. 【推荐】 谨慎使用继承的方式来进行扩展，优先使用聚合/组合的方式来实现。

说明： 不得已使用继承的话，必须符合里氏代换原则，此原则说父类能够出现的地方子类一定能够出现，比如，“把钱交出来”，钱的子类美元、欧元、人民币等都可以出现。

11. 【推荐】 系统设计阶段，根据依赖倒置原则，尽量依赖抽象类与接口，有利于扩展与维护。

说明： 低层次模块依赖于高层次模块的抽象，方便系统间的解耦。

12. 【推荐】 系统设计阶段，注意对扩展开放，对修改闭合。

说明： 极端情况下，交付的代码是不可修改的，同一业务域内的需求变化，通过模块或类的扩展来实现。