木风软件文档中心

Appearance

Java开发手册 ​

前言 ​

现代软件行业的高速发展对开发者的综合素质要求越来越高，不仅是编程知识点，其他维度的知识点也会影响软件交付质量：

  • 混乱的错误码增加排查难度
  • 数据库设计缺陷导致架构/性能风险
  • 工程结构混乱导致维护困难
  • 鉴权漏洞引发安全风险

规约等级 ​

等级约束力说明
强制强必须遵守
推荐中最佳实践
参考弱场景建议

内容格式 ​

  • 说明：规则扩展解释
  • 正例：推荐实现方式
  • 反例：典型错误案例

愿景：码出高效，码出质量。规范不是限制创造性，而是通过统一标准提升协作效率，降低沟通成本。

编程规约 ​

(一) 命名风格 ​

强制规则 ​

  1. 禁止以下划线或美元符号开头/结尾
    ❌ 反例：_name / __name / $Object / name_ / name$ / Object$

  2. 禁止拼音英文混用或直接中文
    ✅ 正例：ali / alibaba / taobao（国际通用名称可视同英文）
    ❌ 反例：

    • DaZhePromotion（打折）
    • getPingfenByName()（评分）
    • String fw（福娃）
    • int 变量名 = 3

  3. 包名规范

    • 全小写，点分隔符间仅一个英语单词
    • 包名单数，类名可复数
      ✅ 正例：
    java
    com.alibaba.ei.kunlun.aap.util // 包名
MessageUtils // 类名（参考Spring框架）

  4. 类名使用 UpperCamelCase（例外：DO/PO/DTO等） ✅ 正例：ForceCode / UserDO / HtmlDTO ❌ 反例：forcecode / UserDo / HTMLDto

  5. 方法/变量使用 lowerCamelCase ✅ 正例：

    java
    localValue
getHttpMessage()
inputUserId

  6. 常量命名全大写+下划线 ✅ 正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME ❌ 反例：MAX_COUNT / EXPIRED_TIME

  7. 禁止不规范缩写 ❌ 反例：

    • AbsClass（AbstractClass）
    • condi（condition）
    • Fu（Function）

推荐规则 ​

  1. 接口规范

    • 方法/属性不加修饰符（包括public）
    • 避免定义接口常量（除非是全局基础常量） ✅ 正例：
    java
    /** Javadoc注释 */
void commit();
String COMPANY = "mufengweilai"; // 全局常量

    ❌ 反例：

    java
    public abstract void mit();

    📝 JDK8+的default方法可为所有实现类提供默认实现

(二) 编码规范 ​

强制规则 ​

  1. 必须使用 Javadoc 注释

    java
    /**
 * 方法功能说明
 * @param param 参数说明
 * @return 返回值说明
 */
✅ 正例：public String getNameById(Long id);

❌ 反例：
// 获取用户名
public String getNameById(Long id);

  2. 方法单一职责原则

    java
    // 正例：拆分多业务逻辑
public void processOrder() {
    validateOrder();
    calculatePrice();
    saveOrder();
}

  3. 禁止重复代码

    java
    // 正例：抽取公共方法
private void logError(String msg) {
    System.err.println("ERROR: " + msg);
}

  4. 提交前代码格式化

    bash
    mvn spring-javaformat:apply

  5. 金额存储规范

    java
    ✅ 正例：long amount = 100; // 单位：分
❌ 反例：double amount = 1.00; // 禁止浮点数

  6. POJO 类禁止默认值

    java
    ❌ 反例：
public class OrderDO {
    private Date createTime = new Date(); // 导致创建时间被意外更新
}

  7. switch-case规范

    java
    switch (type) {
    case 1:
        break; // 必须明确终止
    case 2:
        return; // 或通过return终止
    case 3:
        // 需注释说明继续执行到case5
    case 5:
        break;
    default: // 必须存在且放在最后
}

    💡 break退出 switch 块，return退出方法体

  8. ​ 抽象方法注释要求

    java
    /**
 * 创建订单（必须实现）
 * @param order 订单数据
 * @return 订单ID
 * @throws IllegalArgumentException 参数校验失败时抛出
 */
Long createOrder(Order order);

  9. 类作者注释模板

    Java
    /**
 * @author ${USER}  // IDEA模板
 * @date 2023/08/20
 */
public class OrderService {}

  10. 方法内注释规范

    java
    public void demo() {
    // 单行注释在语句上方
    int count = 0;

    /*
     * 多行注释
     * 与代码保持对齐
     */
}

  11. 枚举注释要求

    java
    public enum OrderStatus {
    /** 待支付 */
    UNPAID,
    /** 已支付 */
    PAID
}

  12. 长方法中断后空行

    java
    public void longMethod() {
    if (error) {
        throw new Exception();
    }
    // 此处空行
    // 后续逻辑...
}

  13. 避免深层 if-else

    java
    // 卫语句示例
public void check(Man man) {
    if (man.isUgly()) {
        System.out.println("拒绝");
        return; // 提前返回
    }
    // 正常逻辑...
}

​ 💡 超过 3 层建议改用策略模式/状态模式

(三) SQL 规范 ​

强制规则 ​

1. 【强制】 ​

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

注意：POJO 类中的布尔类型变量不要加 is 前缀，需设置从 is_xxx 到 Xxx 的映射关系。数据库使用 tinyint 表示是与否，is_xxx 命名明 确取值含义与范围。
说明：任何非负数字段必须是 unsigned。
正例：逻辑删除字段名 is_deleted，1 表示删除，0 表示未删除。

2. 【强制】 ​

表名、字段名必须使用小写字母或数字，禁止数字开头，禁止两下划线间只出现数字。

说明：字段名修改代价大（无法预发布），需慎重考虑。MySQL 在 Windows 不区分大小写，但 Linux 默认区分。因此库名、表名、字段名禁用大写字母 。
正例：aliyun_admin, rdc_config, level3_name
反例：AliyunAdmin, rdcConfig, level_3_name

3. 【强制】 ​

表名不使用复数名词。

说明：表名应表示表内实体内容（而非数量），对应 DO 类名为单数形式。

4. 【强制】 ​

禁用保留字（如 desc, range, match, delayed），参考 MySQL 官方保留字。

5. 【强制】 ​

索引命名规则：

  • 主键索引：pk_字段名
  • 唯一索引：uk_字段名
  • 普通索引：idx_字段名

    说明：pk = primary key，uk = unique key，idx = index。

6. 【强制】 ​

小数类型使用 decimal，禁止使用 float 和 double。

说明：float/double 存在精度损失，可能导致值比较错误。若数据超出 decimal 范围，拆分为整数和小数分开存储。

7. 【强制】 ​

存储字符串长度几乎相等时，使用 char 定长类型。

8. 【强制】 ​

varchar 是可变长字符串，长度禁止超过 5000。超过时应使用 text 类型并独立成表，用主键对应，避免影响其他字段索引率。

9. 【强制】 ​

表必备三字段：

  • id（主键，类型 bigint unsigned，单表自增步长 1）
  • create_time（datetime，表示主动创建）
  • update_time（datetime，表示被动更新）
10. 【强制】 ​

禁用物理删除，必须使用逻辑删除。

说明：逻辑删除可追溯操作，但可能导致唯一主键不唯一，需根据情况解决。

11. 【推荐】 ​

允许适当冗余字段以提高查询性能，但需保证数据一致。冗余字段应满足：

  1. 非频繁修改字段
  2. 非唯一索引字段
  3. 非超长 varchar 或 text 字段

    正例：冗余商品名称（避免查询时调用外部服务）。

12. 【强制】 ​

禁止使用 count(列名) 或 count(常量) 替代 count(*)。

说明：count(*) 是 SQL92 标准统计行数语法，统计包含 NULL 的行；count(列名) 不统计 NULL 行。

13. 【强制】 ​

count(distinct col) 统计非 NULL 不重复行数。count(distinct col1, col2) 若其中一列全为 NULL，则返回 0。

14. 【强制】 ​

当列值全为 NULL 时：

  • count(col) 返回 0
  • sum(col) 返回 NULL（需注意 NPE 问题）

    正例：SELECT IFNULL(SUM(column), 0) FROM table;

15. 【强制】 ​

使用 ISNULL() 判断 NULL 值。

说明：

  1. NULL <> NULL → NULL（非 false）
  2. NULL = NULL → NULL（非 true）
  3. NULL <> 1 → NULL（非 true）
    反例：SELECT * FROM table WHERE column1 IS NULL AND column3 IS NOT NULL;
    性能：ISNULL(column) 执行效率更高。
16. 【强制】 ​

分页查询时，若 count 为 0 应直接返回，避免执行后续分页语句。

17. 【强制】 ​

禁止使用外键与级联，外键概念需在应用层解决。

说明：外键和级联更新适用于单机低并发，不适用于分布式高并发集群（存在更新风暴风险，影响插入速度）。

18. 【强制】 ​

禁止使用存储过程（难以调试、扩展，无移植性）。

19. 【强制】 ​

数据订正（尤其删除/修改）时，必须先 select 确认，避免误操作。

20. 【强制】 ​

多表关联查询或变更时，必须在列名前加表别名（或表名）限定。

(四) 异常处理 ​

  • 统一使用公司异常拦截器
  • 禁止直接调用printStackTrace()

(五) 日志规范 ​

  • 必须使用 Sl4js 输出日志，禁止使用 System.out.println() 输出任何内容；
  • 关键节点必须输出日志，例如逻辑复杂方法输出方法节点、接口调用输出入参和出参等；

(六)文件归档 ​

  • 文件夹标准结构：

    盘符/
├── mfwl
│   ├── 年
│	├── 项目名称
│	│	├── code(装代码文件)
│	│	├── file(项目相关文件)

​ 例如：D:\mfwl\2025\demo_project\code\xxx

本内容仅限内部使用，技术细节以实际代码为准

Copyright © 2019-2025 木风软件 ｜ 木风软件文档中心 版权所有