648 lines
16 KiB
Markdown
648 lines
16 KiB
Markdown
# Lyzsys 项目编码规范
|
||
|
||
## 目录
|
||
|
||
- [1. 命名规范](#1-命名规范)
|
||
- [2. 菜单结构规范](#2-菜单结构规范)
|
||
- [3. 代码结构规范](#3-代码结构规范)
|
||
- [4. 数据库设计规范](#4-数据库设计规范)
|
||
- [5. API 接口规范](#5-api-接口规范)
|
||
- [6. 前端开发规范](#6-前端开发规范)
|
||
|
||
---
|
||
|
||
## 1. 命名规范
|
||
|
||
### 1.1 驼峰命名规范
|
||
|
||
**核心原则**：所有字段名、类名、文件名、变量名的驼峰命名中，**第一个单词不能只有一个字母**。
|
||
|
||
#### 为什么要遵循这个规范？
|
||
|
||
1. **MyBatis Plus 兼容性**：MyBatis Plus 在映射单字母开头的驼峰字段时可能出现问题
|
||
2. **代码可读性**：完整单词更具可读性，便于理解业务含义
|
||
3. **避免错误**：减少字段读取错误和调试困难
|
||
|
||
#### 正确示例 ✅
|
||
|
||
```java
|
||
// 字段命名
|
||
private String projectId; // 而不是 pId
|
||
private String projectName; // 而不是 pName
|
||
private String projectCode; // 而不是 pCode
|
||
private LocalDateTime establishDate; // 而不是 eDate
|
||
|
||
// 特殊情况：如果首字母缩写必须使用，请用完整单词
|
||
private String majorType; // 而不是 mType
|
||
private BigDecimal leaderRatio; // 而不是 lRatio
|
||
private Double kOneCoefficient; // 而不是 k1Coefficient（k1 是业务术语）
|
||
```
|
||
|
||
#### 错误示例 ❌
|
||
|
||
```java
|
||
// 错误：单字母开头
|
||
private String pId; // ❌ 应该是 projectId
|
||
private String mType; // ❌ 应该是 majorType
|
||
private String lRatio; // ❌ 应该是 leaderRatio
|
||
private String k1Coefficient; // ❌ 应该是 kOneCoefficient
|
||
```
|
||
|
||
### 1.2 Java 类命名规范
|
||
|
||
#### 实体类（DO）
|
||
|
||
```java
|
||
// 格式：{业务名称}DO
|
||
ProjectDO.java // 项目实体
|
||
UserDO.java // 用户实体
|
||
OrderDO.java // 订单实体
|
||
```
|
||
|
||
#### VO 类
|
||
|
||
```java
|
||
// 分页查询请求
|
||
{业务名称}PageReqVO.java
|
||
ProjectPageReqVO.java
|
||
|
||
// 响应 VO
|
||
{业务名称}RespVO.java
|
||
ProjectRespVO.java
|
||
|
||
// 保存请求 VO（新增和修改共用）
|
||
{业务名称}SaveReqVO.java
|
||
ProjectSaveReqVO.java
|
||
|
||
// 简单响应 VO（下拉选项等）
|
||
{业务名称}SimpleRespVO.java
|
||
ProjectSimpleRespVO.java
|
||
```
|
||
|
||
#### Mapper 接口
|
||
|
||
```java
|
||
// 格式：{业务名称}Mapper
|
||
ProjectMapper.java
|
||
```
|
||
|
||
#### Service 层
|
||
|
||
```java
|
||
// 接口：{业务名称}Service
|
||
ProjectService.java
|
||
|
||
// 实现：{业务名称}ServiceImpl
|
||
ProjectServiceImpl.java
|
||
```
|
||
|
||
#### Controller 层
|
||
|
||
```java
|
||
// 格式：{业务名称}Controller
|
||
ProjectController.java
|
||
```
|
||
|
||
### 1.3 数据库命名规范
|
||
|
||
#### 表名
|
||
|
||
```sql
|
||
-- 格式：{模块前缀}_{业务名称}（全小写，下划线分隔）
|
||
demo_project -- demo 模块的项目表
|
||
system_user -- system 模块的用户表
|
||
infra_config -- infra 模块的配置表
|
||
```
|
||
|
||
#### 字段名
|
||
|
||
```sql
|
||
-- 使用下划线分隔的小写单词
|
||
project_name -- 项目名称（对应 Java 中的 projectName）
|
||
project_code -- 项目编号
|
||
establish_date -- 立项时间
|
||
|
||
-- 标准字段（所有表必备）
|
||
id -- 主键
|
||
creator -- 创建者
|
||
create_time -- 创建时间
|
||
updater -- 更新者
|
||
update_time -- 更新时间
|
||
deleted -- 删除标记
|
||
tenant_id -- 租户ID（多租户表必备）
|
||
```
|
||
|
||
### 1.4 包名规范
|
||
|
||
```
|
||
cn.iocoder.lyzsys.module.{模块名}.{分层}
|
||
|
||
示例：
|
||
cn.iocoder.lyzsys.module.demo.controller.admin.project
|
||
cn.iocoder.lyzsys.module.demo.service.project
|
||
cn.iocoder.lyzsys.module.demo.dal.dataobject.project
|
||
cn.iocoder.lyzsys.module.demo.dal.mysql.project
|
||
```
|
||
|
||
### 1.5 前端命名规范
|
||
|
||
#### Vue 组件名
|
||
|
||
```javascript
|
||
// 页面组件（defineOptions name）
|
||
DemoProject // 项目列表页
|
||
DemoProjectForm // 项目表单组件
|
||
|
||
// 文件名（kebab-case）
|
||
index.vue // 列表页
|
||
ProjectForm.vue // 表单组件
|
||
```
|
||
|
||
#### API 文件
|
||
|
||
```typescript
|
||
// 文件路径
|
||
src/api/demo/project/index.ts
|
||
|
||
// 接口命名（驼峰）
|
||
export const getProjectPage = () => {}
|
||
export const createProject = () => {}
|
||
export const updateProject = () => {}
|
||
export const deleteProject = () => {}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 菜单结构规范
|
||
|
||
### 2.1 菜单层级规范
|
||
|
||
**原则**：业务功能菜单优先展示，系统管理功能放在最后。
|
||
|
||
#### 推荐的菜单顺序
|
||
|
||
```
|
||
1. 业务菜单（sort: 1-90）
|
||
├── 项目管理（一级菜单，sort: 1）
|
||
│ └── 项目列表（二级菜单，sort: 1）
|
||
├── 客户管理（一级菜单，sort: 2）
|
||
│ └── 客户列表（二级菜单，sort: 1）
|
||
└── ...
|
||
|
||
98. 系统管理（sort: 98）
|
||
├── 用户管理
|
||
├── 角色管理
|
||
├── 菜单管理
|
||
└── ...
|
||
|
||
99. 基础设施（sort: 99）
|
||
├── 代码生成
|
||
├── 文件管理
|
||
└── ...
|
||
```
|
||
|
||
### 2.2 菜单配置规范
|
||
|
||
#### 一级菜单（目录）
|
||
|
||
```sql
|
||
INSERT INTO `system_menu` (
|
||
`id`, `name`, `permission`, `type`, `sort`, `parent_id`,
|
||
`path`, `icon`, `component`, `component_name`,
|
||
`status`, `visible`, `keep_alive`, `always_show`,
|
||
`creator`, `create_time`, `updater`, `update_time`, `deleted`
|
||
) VALUES (
|
||
3000, -- ID（建议按模块分配段，如 demo: 3000-3999）
|
||
'项目管理', -- 名称
|
||
'', -- 权限标识（一级菜单为空）
|
||
1, -- 类型：1=目录
|
||
1, -- 排序（业务菜单建议 1-90）
|
||
0, -- 父级ID（0表示顶级）
|
||
'/demo', -- 路由路径
|
||
'ep:files', -- 图标
|
||
NULL, -- 组件路径（目录为NULL）
|
||
NULL, -- 组件名称（目录为NULL）
|
||
0, -- 状态：0=正常
|
||
b'1', -- 是否可见
|
||
b'1', -- 是否缓存
|
||
b'1', -- 是否总是显示
|
||
'1', -- 创建者
|
||
NOW(), -- 创建时间
|
||
'1', -- 更新者
|
||
NOW(), -- 更新时间
|
||
b'0' -- 是否删除
|
||
);
|
||
```
|
||
|
||
#### 二级菜单（菜单页面）
|
||
|
||
```sql
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3001, -- ID
|
||
'项目列表', -- 名称
|
||
'', -- 权限标识（菜单页面为空）
|
||
2, -- 类型：2=菜单
|
||
1, -- 排序
|
||
3000, -- 父级ID（对应一级菜单ID）
|
||
'project', -- 路由路径
|
||
'ep:document', -- 图标
|
||
'demo/project/index', -- 组件路径
|
||
'DemoProject', -- 组件名称（对应 Vue defineOptions name）
|
||
0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
```
|
||
|
||
#### 三级菜单（按钮权限）
|
||
|
||
```sql
|
||
-- 查询权限
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3002, '项目查询', 'demo:project:query', 3, 1, 3001,
|
||
'', '', '', NULL, 0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
|
||
-- 新增权限
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3003, '项目新增', 'demo:project:create', 3, 2, 3001,
|
||
'', '', '', NULL, 0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
|
||
-- 修改权限
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3004, '项目修改', 'demo:project:update', 3, 3, 3001,
|
||
'', '', '', NULL, 0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
|
||
-- 删除权限
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3005, '项目删除', 'demo:project:delete', 3, 4, 3001,
|
||
'', '', '', NULL, 0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
|
||
-- 导出权限
|
||
INSERT INTO `system_menu` (...) VALUES (
|
||
3006, '项目导出', 'demo:project:export', 3, 5, 3001,
|
||
'', '', '', NULL, 0, b'1', b'1', b'1',
|
||
'1', NOW(), '1', NOW(), b'0'
|
||
);
|
||
```
|
||
|
||
### 2.3 权限标识规范
|
||
|
||
```
|
||
格式：{模块名}:{业务}:{操作}
|
||
|
||
示例：
|
||
demo:project:query -- demo模块，项目业务，查询操作
|
||
demo:project:create -- demo模块，项目业务，新增操作
|
||
demo:project:update -- demo模块，项目业务，修改操作
|
||
demo:project:delete -- demo模块，项目业务，删除操作
|
||
demo:project:export -- demo模块，项目业务，导出操作
|
||
```
|
||
|
||
### 2.4 菜单 ID 分配规范
|
||
|
||
为避免 ID 冲突，建议按模块分配 ID 段：
|
||
|
||
| 模块 | ID 范围 | 说明 |
|
||
|-----|---------|------|
|
||
| system | 1-999 | 系统核心模块 |
|
||
| infra | 1000-1999 | 基础设施模块 |
|
||
| member | 2000-2999 | 会员模块 |
|
||
| demo | 3000-3999 | Demo 示例模块 |
|
||
| bpm | 4000-4999 | 工作流模块 |
|
||
| mall | 5000-5999 | 商城模块 |
|
||
| ... | ... | 其他业务模块 |
|
||
|
||
---
|
||
|
||
## 3. 代码结构规范
|
||
|
||
### 3.1 模块目录结构
|
||
|
||
```
|
||
lyzsys-module-{模块名}/
|
||
├── pom.xml # Maven 配置
|
||
└── src/main/java/cn/iocoder/lyzsys/module/{模块名}/
|
||
├── controller/ # 控制器层
|
||
│ └── admin/ # 管理后台接口
|
||
│ └── {业务}/ # 业务模块
|
||
│ ├── {业务}Controller.java # 控制器
|
||
│ └── vo/ # VO 对象
|
||
│ ├── {业务}PageReqVO.java # 分页请求
|
||
│ ├── {业务}RespVO.java # 响应 VO
|
||
│ └── {业务}SaveReqVO.java # 保存请求
|
||
├── service/ # 服务层
|
||
│ └── {业务}/
|
||
│ ├── {业务}Service.java # 服务接口
|
||
│ └── {业务}ServiceImpl.java # 服务实现
|
||
├── dal/ # 数据访问层
|
||
│ ├── dataobject/ # 数据对象
|
||
│ │ └── {业务}/
|
||
│ │ └── {业务}DO.java # 实体类
|
||
│ └── mysql/ # Mapper 接口
|
||
│ └── {业务}/
|
||
│ └── {业务}Mapper.java # Mapper
|
||
├── convert/ # 对象转换（可选）
|
||
│ └── {业务}Convert.java
|
||
├── enums/ # 枚举类
|
||
│ └── ErrorCodeConstants.java # 错误码
|
||
└── api/ # 对外 API（可选）
|
||
└── {业务}Api.java
|
||
```
|
||
|
||
### 3.2 分层职责
|
||
|
||
#### Controller 层
|
||
|
||
- 接收 HTTP 请求
|
||
- 参数校验（使用 @Valid）
|
||
- 权限控制（使用 @PreAuthorize）
|
||
- 调用 Service 层
|
||
- 返回统一响应
|
||
|
||
#### Service 层
|
||
|
||
- 业务逻辑处理
|
||
- 数据校验
|
||
- 事务控制
|
||
- 调用 Mapper 层
|
||
|
||
#### DAL 层
|
||
|
||
- 数据访问
|
||
- SQL 操作
|
||
- 不包含业务逻辑
|
||
|
||
---
|
||
|
||
## 4. 数据库设计规范
|
||
|
||
### 4.1 表设计规范
|
||
|
||
#### 标准字段（所有表必备）
|
||
|
||
```sql
|
||
CREATE TABLE `{表名}` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
||
-- 业务字段
|
||
...
|
||
-- 标准字段
|
||
`creator` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT '' COMMENT '创建者',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updater` varchar(64) COLLATE utf8mb4_unicode_ci DEFAULT '' COMMENT '更新者',
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
`deleted` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否删除',
|
||
PRIMARY KEY (`id`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='表注释';
|
||
```
|
||
|
||
#### 多租户表额外字段
|
||
|
||
```sql
|
||
`tenant_id` bigint NOT NULL DEFAULT 0 COMMENT '租户编号',
|
||
```
|
||
|
||
### 4.2 字段类型规范
|
||
|
||
| Java 类型 | MySQL 类型 | 说明 |
|
||
|-----------|-----------|------|
|
||
| Long | bigint | ID、数量等 |
|
||
| String | varchar | 字符串 |
|
||
| Integer | int | 状态、类型等 |
|
||
| LocalDateTime | datetime | 日期时间 |
|
||
| LocalDate | date | 日期 |
|
||
| BigDecimal | decimal | 金额、精确数值 |
|
||
| Boolean | bit(1) | 布尔值 |
|
||
|
||
### 4.3 索引规范
|
||
|
||
```sql
|
||
-- 主键索引
|
||
PRIMARY KEY (`id`)
|
||
|
||
-- 唯一索引（业务唯一字段）
|
||
UNIQUE KEY `uk_project_code` (`project_code`)
|
||
|
||
-- 普通索引（常用查询字段）
|
||
KEY `idx_project_name` (`project_name`)
|
||
|
||
-- 组合索引（多字段联合查询）
|
||
KEY `idx_tenant_status` (`tenant_id`, `status`)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. API 接口规范
|
||
|
||
### 5.1 RESTful 风格
|
||
|
||
| 操作 | HTTP 方法 | URL | 说明 |
|
||
|-----|----------|-----|------|
|
||
| 查询列表 | GET | /{模块}/{业务}/page | 分页查询 |
|
||
| 查询详情 | GET | /{模块}/{业务}/get | 根据ID查询 |
|
||
| 新增 | POST | /{模块}/{业务}/create | 创建 |
|
||
| 修改 | PUT | /{模块}/{业务}/update | 更新 |
|
||
| 删除 | DELETE | /{模块}/{业务}/delete | 删除 |
|
||
| 批量删除 | DELETE | /{模块}/{业务}/delete-list | 批量删除 |
|
||
| 导出 | GET | /{模块}/{业务}/export-excel | 导出Excel |
|
||
|
||
### 5.2 统一响应格式
|
||
|
||
```java
|
||
// 成功响应
|
||
{
|
||
"code": 0,
|
||
"data": {...},
|
||
"msg": ""
|
||
}
|
||
|
||
// 失败响应
|
||
{
|
||
"code": 1001,
|
||
"data": null,
|
||
"msg": "错误信息"
|
||
}
|
||
|
||
// 分页响应
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"list": [...],
|
||
"total": 100
|
||
},
|
||
"msg": ""
|
||
}
|
||
```
|
||
|
||
### 5.3 接口注解规范
|
||
|
||
```java
|
||
@Tag(name = "管理后台 - 项目管理")
|
||
@RestController
|
||
@RequestMapping("/demo/project")
|
||
@Validated
|
||
public class ProjectController {
|
||
|
||
@PostMapping("/create")
|
||
@Operation(summary = "创建项目")
|
||
@PreAuthorize("@ss.hasPermission('demo:project:create')")
|
||
public CommonResult<Long> createProject(@Valid @RequestBody ProjectSaveReqVO createReqVO) {
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 前端开发规范
|
||
|
||
### 6.1 目录结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 接口
|
||
│ └── {模块}/
|
||
│ └── {业务}/
|
||
│ └── index.ts # API 定义
|
||
└── views/ # 页面
|
||
└── {模块}/
|
||
└── {业务}/
|
||
├── index.vue # 列表页
|
||
└── {业务}Form.vue # 表单组件
|
||
```
|
||
|
||
### 6.2 组件规范
|
||
|
||
#### 列表页面
|
||
|
||
```vue
|
||
<template>
|
||
<!-- 搜索工作栏 -->
|
||
<ContentWrap>
|
||
<el-form>...</el-form>
|
||
</ContentWrap>
|
||
|
||
<!-- 列表 -->
|
||
<ContentWrap>
|
||
<el-table>...</el-table>
|
||
<Pagination />
|
||
</ContentWrap>
|
||
|
||
<!-- 表单弹窗 -->
|
||
<{业务}Form ref="formRef" @success="getList" />
|
||
</template>
|
||
|
||
<script lang="ts" setup>
|
||
defineOptions({ name: '{模块}{业务}' })
|
||
// ...
|
||
</script>
|
||
```
|
||
|
||
#### 表单组件
|
||
|
||
```vue
|
||
<template>
|
||
<Dialog v-model="dialogVisible" :title="dialogTitle">
|
||
<el-form>...</el-form>
|
||
<template #footer>
|
||
<el-button type="primary" @click="submitForm">确 定</el-button>
|
||
<el-button @click="dialogVisible = false">取 消</el-button>
|
||
</template>
|
||
</Dialog>
|
||
</template>
|
||
|
||
<script lang="ts" setup>
|
||
defineOptions({ name: '{模块}{业务}Form' })
|
||
defineExpose({ open })
|
||
// ...
|
||
</script>
|
||
```
|
||
|
||
### 6.3 权限控制
|
||
|
||
```vue
|
||
<!-- 按钮权限 -->
|
||
<el-button
|
||
v-hasPermi="['demo:project:create']"
|
||
type="primary"
|
||
@click="openForm('create')"
|
||
>
|
||
新增
|
||
</el-button>
|
||
|
||
<!-- 路由权限在菜单配置中控制 -->
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 最佳实践
|
||
|
||
### 7.1 代码注释
|
||
|
||
```java
|
||
/**
|
||
* 项目管理 Service 接口
|
||
*
|
||
* @author lyzsys
|
||
*/
|
||
public interface ProjectService {
|
||
|
||
/**
|
||
* 创建项目
|
||
*
|
||
* @param createReqVO 项目信息
|
||
* @return 项目编号
|
||
*/
|
||
Long createProject(ProjectSaveReqVO createReqVO);
|
||
}
|
||
```
|
||
|
||
### 7.2 异常处理
|
||
|
||
```java
|
||
// 使用统一的业务异常
|
||
throw exception(PROJECT_NOT_EXISTS);
|
||
throw exception(PROJECT_CODE_DUPLICATE);
|
||
```
|
||
|
||
### 7.3 日志规范
|
||
|
||
```java
|
||
@Slf4j
|
||
public class ProjectServiceImpl implements ProjectService {
|
||
|
||
@Override
|
||
public Long createProject(ProjectSaveReqVO createReqVO) {
|
||
log.info("[createProject] 创建项目，项目编号：{}", createReqVO.getProjectCode());
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 检查清单
|
||
|
||
在提交代码前，请检查：
|
||
|
||
- [ ] 所有字段命名遵循驼峰规范，无单字母开头
|
||
- [ ] 菜单配置完整（一级、二级、按钮权限）
|
||
- [ ] 业务菜单排序在系统管理之前
|
||
- [ ] 权限标识格式正确（{模块}:{业务}:{操作}）
|
||
- [ ] 数据库表包含标准字段
|
||
- [ ] API 接口遵循 RESTful 风格
|
||
- [ ] 代码注释完整
|
||
- [ ] 前端权限控制正确
|
||
|
||
---
|
||
|
||
**文档版本**：v1.0
|
||
**最后更新**：2024年
|
||
**维护者**：开发团队
|