编码规范

本篇汇总 Java、Vue、SQL 三端的命名规范、注释规范和格式化要求。你在编写任何代码前都应遵循这些约定。

Java 规范

命名

类型	规则	示例
类名	UpperCamelCase	SysUserController
方法名	lowerCamelCase	getUserById
变量名	lowerCamelCase	userId
常量	UPPER_SNAKE_CASE	MAX_PAGE_SIZE
包名	全小写	com.mdframe.forge.admin
枚举值	UPPER_SNAKE_CASE	StatusEnum.ENABLED

注释

• 类级注释：使用 Javadoc，说明类的职责
• 公共方法：必须有 Javadoc，包含 @param 和 @return
• 复杂逻辑：行内注释说明为什么，而非做了什么

/**
 * 用户服务，负责用户 CRUD 和权限分配
 */
public interface SysUserService {
    /**
     * 分页查询用户
     * @param query 查询条件
     * @return 分页结果
     */
    IPage<SysUser> page(SysUserQuery query);
}

格式化

• 缩进：4 个空格
• 行宽：不超过 120 字符
• import：禁止通配符 import xxx.*

Vue 规范

命名

类型	规则	示例
组件文件	PascalCase	DictSelect.vue
组件名	PascalCase	<DictSelect />
组合式函数	camelCase，use 前缀	useDict
Props	camelCase	dictType
事件	kebab-case	@value-change
CSS 类	kebab-case	user-card

结构

<script setup lang="ts">
import { ref, computed } from 'vue'
// 1. 导入
// 2. Props / Emits
// 3. 响应式数据
// 4. 计算属性
// 5. 方法
// 6. 生命周期
</script>

<template>
  <!-- 模板 -->
</template>

<style scoped lang="scss">
/* 样式 */
</style>

SQL 规范

命名

类型	规则	示例
表名	小写 + 下划线，带前缀	sys_user、biz_order
字段名	小写 + 下划线	create_time
索引名	idx_ 前缀	idx_user_name
唯一索引	uk_ 前缀	uk_tenant_username

格式化

• 关键字大写：SELECT、FROM、WHERE
• 缩进：每个条件独占一行，对齐
• 参数化查询：使用 #{param}，禁止 ${param} 拼接

SELECT id, username, nickname, status
FROM sys_user
WHERE del_flag = 0
  AND tenant_id = #{tenantId}
  AND status = #{status}
ORDER BY create_time DESC

请求体与状态

• Controller @RequestBody 必须用 DTO/VO，禁止用 Map 接收固定字段请求
• 业务状态在 Java 中必须用枚举，禁止 setStatus(2) 这类魔法值
• Mapper XML 可以继续写数字字面量，不要把 Java 类全名绑进 SQL

通用约定

• 字符编码统一 UTF-8
• 换行符使用 LF
• 文件末尾保留一个空行
• 禁止提交 IDE 配置文件（.idea/、.vscode/）