yangxuan/openclaw-config

Fork 0

Files

T

杨轩 fcb30e1c69 骨架代码规范

2026-08-04 14:56:20 +08:00

13 KiB

Raw Permalink Blame History

MICA-Server 开发规范

本文档是 mica-server 项目的权威开发规范，所有开发人员必须严格遵守。

一、技术栈与版本

1.1 核心技术栈

类别	技术	版本	说明
JDK	Java	1.8	禁止使用 Java 9+ 特性
框架	Spring Boot	2.6.7	统一版本
ORM	MyBatis-Plus	3.5.1	禁止手写原生 SQL（除非性能优化）
构建工具	Maven	3.6+	统一使用 Maven
数据库	MySQL	8.0+	HikariCP 连接池
注册/配置中心	Nacos	2.x	服务注册与配置管理

1.2 工具库使用优先级

优先使用: com.witsoft.common-utils 中 utils 包封装的类和方法
其次使用: Hutool 工具库
再次使用: Apache Commons 系列
禁止: 重复造轮子

二、代码规范

2.1 命名规范

类命名

类名: UpperCamelCase 风格，必须为名词
- 正确：UserController, UserService
- 例外：领域模型 DO/BO/DTO/VO 等后缀
抽象类: 使用 Abstract 或 Base 开头
- 例如：AbstractService, BaseController
异常类: 使用 Exception 结尾
- 例如：BizException, ValidationException
测试类: 以被测试类名开头，以 Test 结尾
- 例如：UserServiceTest

方法和变量命名

方法名/变量名: lowerCamelCase 风格
- 正确：queryUserList, localName, getUserName
- 禁止：拼音与英文混合、直接使用中文
Service/DAO 层方法前缀:
- 获取单个/多个对象：query (如 queryUser, queryUserList)
- 插入：insert 或 save (如 insertUser, saveOrder)
- 删除：delete 或 batchDelete (如 deleteUser, batchDeleteOrders)
- 修改：update (如 updateUser, updateOrderStatus)

常量命名

常量名: UPPER_CASE_UNDERSCORE 风格，力求语义完整
- 正确：MAX_USER_COUNT, DEFAULT_PAGE_SIZE
- 禁止：不规范的缩写 (如 AbsClass 代替 AbstractClass)
常量类组织: 按功能分类，禁止一个常量类维护所有常量
- 例如：CacheConsts, ConfigConsts, UserConsts

包命名

包名: 统一使用小写，点分隔符之间有且仅有一个单词
- 正确：com.witsoft.mica.service, com.witsoft.util
- 禁止：com.witsoft.mica.services (复数)

其他命名规则

数组定义: String[] args (中括号是数组类型的一部分)
布尔类型变量: 禁止加 is 前缀 (避免序列化错误)
- 正确：boolean success, 方法名 getSuccess()
- 错误：boolean isSuccess, 方法名 isSuccess()

2.2 代码格式

大括号使用

// 空代码块
if (flag == 0) {}

// 非空代码块
if (flag == 1) {
    System.out.println("world");
} else {
    System.out.println("ok");
}

规则:

左大括号前不换行
左大括号后换行
右大括号前换行
右大括号后还有 else 等代码则不换行
右大括号表示终止则必须换行

缩进与空格

缩进: 4 个空格，禁止使用 tab 字符
单行字符数: 不超过 200 个，超出需换行
运算符: 左右必须有一个空格
关键词: if/for/while 等与括号之间必须有一个空格
方法参数: 多个参数逗号后必须加空格
- 例如：method("aa", "bb", "cc")

换行规则

第二行相对第一行缩进 4 个空格，从第三行开始不再继续缩进
运算符与下文一起换行
方法调用的点符号与下文一起换行
多个参数超长时，逗号后换行

文件编码

IDE 编码: UTF-8
换行符: Unix 格式 (LF)，禁止使用 Windows 格式 (CRLF)

2.3 OOP 规约

静态访问: 直接用类名访问静态变量/方法，禁止通过对象引用访问

// 正确
User user = UserService.getDefaultUser();

// 错误
User user = new UserService().getDefaultUser();

覆写方法: 必须加 @Override 注解
可变参数:
- 相同参数类型、相同业务含义才可使用
- 必须放置在参数列表最后
- 避免使用 Object 类型
```
public User getUsers(String type, Integer... ids)
```
接口签名:
- 原则上不允许修改方法签名
- 接口过时必须加 @Deprecated 注解，并说明新接口

equals 方法: 使用常量或确定有值的对象调用

// 正确
"test".equals(object);

// 错误
object.equals("test"); // 可能 NPE

序列化:
- 新增属性时不修改 serialVersionUID
- 完全不兼容升级时修改 serialVersionUID
toString 方法: POJO 类必须编写，继承的 POJO 需调用 super.toString()

2.4 注释规范

类注释模板

/**
 * @menu : 类描述
 * @Description : 类描述
 * @ModifyBrief :
 * @Author : git 账号
 * @Date : 创建时间
 * @Version : 3.0
 * @Param :
 * @Return :
 */

方法注释模板

/**
 * @Description : 方法描述
 * @ModifyBrief :
 * @Author : git 账号
 * @Date : 创建时间
 * @Version : 3.0
 * @Param : 参数说明
 * @Return : 返回值说明
 */

注释规则

所有公共接口和类必须包含 Javadoc
注释语言: 中文描述业务背景，技术术语保留英文 (如 NPE、DTO、API)
禁止生成 "Gets the value of X" 这类无意义的 getter/setter 注释
复杂算法必须在代码块上方解释核心逻辑
禁止使用 HTML 标签
代码内注释: 复杂逻辑必须包含行内注释，解释"为什么这样做"而非"做了什么"
代码与注释比例: 约 5:1，行注释使用 // xxxxxx

三、异常处理规范

3.1 异常捕获

禁止: 捕获 Exception 或 Throwable 后不做任何处理 (吞掉异常)
规范: 必须捕获具体的异常类
日志: 捕获异常时，调用 GlobalException.getExceptionMessage(e)

3.2 异常示例

// 正确
try {
    userService.queryUser(userId);
} catch (UserNotFoundException e) {
    log.error("用户不存在：userId={}", userId, e);
    throw new BizException("用户不存在");
}

// 错误 - 禁止吞掉异常
try {
    userService.queryUser(userId);
} catch (Exception e) {
    // 什么都不做
}

四、数据库规范

4.1 建表规约

表名命名

不使用复数名词
业务表前缀: mica_
命名规则: 小写字母或数字，下划线间隔
- 正确：mica_user_info, mica_order_detail
- 禁止：mica_users, 1_table, table__name

标准字段 (所有业务表必须包含)

字段名	类型	长度	是否 NULL	主键	注释
`id`	varchar	50	否	是	自然主键
`ecid`	varchar	100	否	否	企业编码 (多租户)
`create_time`	datetime	3	是	否	创建时间
`created_by`	varchar	50	是	否	创建人
`update_time`	datetime	3	是	否	修改时间
`updated_by`	varchar	50	是	否	修改人
`delete_time`	datetime	3	是	否	删除时间
`deleted_by`	varchar	50	是	否	删除人
`delete_mark`	tinyint	1	默认 0	否	删除标志 0:未删除 1:已删除

字段命名

小写字母或数字，下划线间隔
禁止数字开头
禁止两个下划线中间只有数字
及时更新字段注释: 修改字段含义或追加状态时

索引命名

唯一索引: uk_字段名 (如 uk_user_name)
普通索引: idx_字段名 (如 idx_create_time)

数据类型

小数: 必须使用 decimal，禁止使用 float 和 double
字符串:
- varchar 长度不超过 5000
- 超过 5000 使用 text 类型，独立成表，用主键对应

4.2 索引规约

唯一特性字段: 即使组合字段也必须建立唯一索引
关联查询: 超过 3 个表禁止 join，被关联字段必须有索引
varchar 索引: 必须指定索引长度 (一般 20 即可达到 90% 区分度)

4.3 SQL 规约

COUNT 统计: 使用 count(*)，禁止使用 count(列名) 或 count(常量)
NULL 判断: 使用 ISNULL() 函数
- NULL <> NULL 返回 NULL
- NULL = NULL 返回 NULL
IN 操作: 能避免则避免，可用 EXISTS 替换，集合元素控制在 1000 个内
数据订正: 删除/修改前先 SELECT 确认

4.4 ORM 规约

查询字段: 禁止使用 *，必须明确写明需要的字段
参数传递: 使用 #{}，禁止使用 ${} (防止 SQL 注入)
返回结果: 禁止直接使用 HashMap 或 Hashtable
更新接口: 只更新有改动的字段，禁止全字段更新
事务控制:
- 不要滥用 @Transactional
- 考虑缓存回滚、消息补偿等回滚方案

五、统一响应格式

所有 Controller 层方法返回必须遵循以下 JSON 结构：

{
  "code": 200,
  "msg": "操作成功",
  "data": [],
  "extra": {},
  "success": true
}

六、项目结构规范

6.1 标准分层结构

com.witsoft.mica.xxx/
├── controller/        # REST 接口层
├── domain/           # DTO / VO / 查询参数
├── entity/           # 数据库实体 (DO)
├── mapper/           # MyBatis-Plus Mapper
└── service/          # 业务逻辑层
    ├── XxxService.java
    └── impl/
        └── XxxServiceImpl.java

6.2 各层职责

Controller: 参数校验、调用 Service、返回统一响应
Service: 业务逻辑、事务控制、数据填充
Mapper: 数据持久化 (仅简单 CRUD，复杂查询用 XML)
Entity: 数据库实体映射 (DO)
Domain:
- DTO: 数据传输对象
- VO: 展示对象
- Query: 查询参数对象

七、开发注意事项

7.1 代码复用

复用优先: 逻辑雷同时提取公共方法，避免重复代码
工具类优先: 优先使用已有工具类方法

7.2 物料数据规范

业务表仅存物料 id: 物料相关字段仅存 material_id
关联查询填充: 编码、名称、规格、单位等通过关联查询填充
填充在 Service 层: 关联数据填充逻辑统一在 Service 层处理

7.3 字典使用

优先使用 DictService: 字典取值优先使用 DictService 公共方法
禁止手写: 不手写字典查询逻辑

7.4 Java 8 兼容性

禁止 List.of(): Java 8 不兼容
使用: Collections.emptyList() 替代

7.5 版本管理

首个版本直接改 DDL: v1.0 脚本直接修改建表语句
不需要 ALTER TABLE: 初始版本不需要写迁移脚本

八、Git 提交约定

8.1 提交规范

禁止 Agent commit: Agent 不做任何 commit 操作，只允许查看、修改代码
Commit Message: 提示 commit 时必须附带 commit message，让用户可直接复制运行
用户手动提交: 如需提交代码，由用户手动执行 commit

8.2 配置文件

application.yml / application-local.yml: 由用户自行提交
Agent 绝不碰: 这两个配置文件的版本管理

九、部署约定

9.1 部署规范

禁止自动部署: Agent 不做任何自动部署操作
用户手动决定: 代码修改后由用户手动决定何时部署

9.2 数据库脚本管理

所有数据库脚本必须按顺序编号，并在 MEMORY.md 中记录执行状态：

✅ 00-init.sql - 基础表结构
✅ 10-system.sql - 系统数据
✅ 20-master-data-init.sql - 基础数据
...

十、物料近似查询规范 (2026-05-29 产品决策)

10.1 searchSimilar() 优先级

产品决定不查询规格字段，按以下优先级分步查询：

名称精确匹配 (material_name = keyword) — 优先级最高
名称前缀匹配 (material_name LIKE 'keyword%')
名称模糊匹配 (material_name LIKE '%keyword%')
编码模糊匹配 (material_code LIKE '%keyword%') — 兜底

10.2 去重原则

已在前置层级匹配的物料不再在后置层级重复出现。

10.3 旧方法保留

保留旧 searchByNameLike() 方法不动，保持向后兼容。

附录：快速参考

命名速查表

类型	规范	示例
类名	UpperCamelCase	`UserController`
方法名	lowerCamelCase	`queryUserList`
变量名	lowerCamelCase	`userName`
常量名	UPPER_CASE_UNDERSCORE	`MAX_COUNT`
包名	小写单数	`com.witsoft.util`
表名	小写 + 下划线	`mica_user_info`
字段名	小写 + 下划线	`user_name`
唯一索引	`uk_字段名`	`uk_user_name`
普通索引	`idx_字段名`	`idx_create_time`

Service 方法前缀速查

操作	前缀	示例
查询单个	`query`	`queryUser`
查询列表	`query`	`queryUserList`
插入	`insert`/`save`	`insertUser`
删除	`delete`	`deleteUser`
批量删除	`batchDelete`	`batchDeleteUsers`
更新	`update`	`updateUser`

版本: 1.0
最后更新: 2026-08-04
维护者: 后端开发团队

13 KiB Raw Permalink Blame History