Skip to content

Commit 4dea87b

Browse files
haoxianruihaoxianrui
committed
补充代码规范
1 parent 0da6427 commit 4dea87b

File tree

2 files changed

+132
-80
lines changed

2 files changed

+132
-80
lines changed

‎src/standard/1.前端规范/README.md

+83-25
Original file line numberDiff line numberDiff line change
@@ -27,39 +27,97 @@ tag:
2727
---
2828

2929
### 方法命名
30-
| 方法类型 | 命名模式 | 示例 |
31-
|----------------|-------------|---------------------------|
32-
| 数据获取 | fetchXxx | `fetchUserList` |
33-
| 事件处理 | handleXxx | `handleSubmit` |
34-
| 状态变更 | updateXxx | `updateLoadingStatus` |
35-
| 表单验证 | validate | `validateEmailFormat` |
36-
| 工具方法 | 动词+名词 | `formatCurrency` |
37-
| 初始化操作 |initializeXxx | `initializeMap` |
38-
| 数据处理 |processXxx | `processImageData` |
39-
| 权限校验 |checkXxxPermission | `checkEditPermission` |
30+
| **方法类别** | **命名规则** | **示例** | **适用场景** | **最佳实践** |
31+
|-----------------------|----------------------------|----------------------------------------|----------------------------------------|----------------------------------------------------------------------------|
32+
| **DOM事件处理** | `handle[元素][动作]` | `handleSubmitClick` | 按钮点击/表单提交 | 保留原生事件参数：`(e: MouseEvent)` |
33+
| **自定义事件处理** | `handle[组件][事件]` | `handleUserSearch` | 子组件触发的搜索事件 | 使用`@on-event-name`格式定义自定义事件 |
34+
| **数据获取** | `fetch[资源]Data` | `fetchUserList` | API数据请求 | 配合`loading`状态：`const userListLoading = ref(false)` |
35+
| **数据提交** | `submit[表单类型]` | `submitLoginForm` | 表单提交操作 | 使用`async/await`处理异步 |
36+
| **状态更新** | `update[状态名]` / `set[状态名]` | `setDarkMode` | 切换夜间模式 | 复杂更新应包含业务逻辑：`updatePagination()` |
37+
| **验证方法** | `validate[字段名]` | `validateEmailFormat` | 表单字段校验 | 返回布尔值或错误消息 |
38+
| **组件暴露方法** | `[动作] + 名词` | `resetForm` | 通过`defineExpose`暴露的方法 | 使用动词开头：`refreshData` |
39+
| **异步操作** | `[动作]Async` | `uploadFileAsync` | 文件上传等异步任务 | 始终包含错误处理逻辑 |
40+
| **工具方法** | `[功能描述]` | `formatCurrency` | 通用工具函数 | 使用纯函数实现，添加完整类型注解 |
41+
| **副作用操作** | `handle[效果][动作]` | `handleRouteChange` | 路由变化监听 | 在`onMounted`/`onUnmounted`中管理生命周期 |
42+
| **状态切换** | `toggle[状态]` | `toggleSidebar` | 显示/隐藏切换操作 | 使用布尔值控制状态变化 |
43+
| **批量操作** | `batch[动作]` | `batchDeleteItems` | 多选删除操作 | 操作前进行二次确认 |
44+
| **数据处理** | `process[数据类型]` | `processCSVData` | CSV文件解析 | 返回处理后的标准数据结构 |
45+
| **缓存操作** | `cache[资源]` | `cacheUserProfile` | 本地存储管理 | 设置有效期限，配合序列化操作 |
46+
| **权限校验** | `check[权限类型]` | `checkAdminAccess` | 路由守卫/功能权限控制 | 返回
4047
---
4148

4249
## 导入顺序规范
4350

44-
```typescript
45-
// 1. 第三方库
46-
import { ElMessage } from 'element-plus';
47-
import { ref, computed } from 'vue';
48-
49-
// 2. 项目工具类
50-
import { getToken } from '@/utils/auth';
51+
```
52+
+ 1. 框架核心
53+
+ 2. 类型定义
54+
+ 3. 状态管理
55+
+ 4. API服务
56+
+ 5. UI组件
57+
+ 6. 工具模块
58+
+ 7. 静态资源
5159
52-
// 3. Store模块
53-
import { useUserStore } from '@/stores/user.ts';
60+
```
5461

55-
// 4. 类型定义
56-
import type { UserProfile } from '@/types/user.d.ts';
62+
- **最佳实践**
5763

58-
// 5. 父级组件
59-
import AppMain from '@/layout/AppMain/index.vue';
64+
```typescript
65+
// 框架核心
66+
import { defineOptions } from "vue";
67+
68+
// 组合式API
69+
import { ref, reactive } from "vue";
70+
71+
// 类型定义（集中前置）
72+
import type { UserForm, UserPageQuery, UserPageVO } from "@/api/system/user";
73+
74+
// Store (状态管理)
75+
import { useDictStore } from "@/store";
76+
77+
// API 服务 (按模块分组)
78+
import UserAPI from "@/api/system/user";
79+
import DeptAPI from "@/api/system/dept";
80+
import RoleAPI from "@/api/system/role";
81+
82+
// 子组件 (按父子关系)
83+
import DeptTree from "./components/DeptTree.vue";
84+
import UserImport from "./components/UserImport.vue";
85+
86+
// 组件元数据 (优先声明)
87+
defineOptions({
88+
name: "User",
89+
inheritAttrs: false,
90+
});
91+
92+
// Store 实例化 (紧接声明)
93+
const dictStore = useDictStore();
94+
95+
// DOM 引用 (前置声明)
96+
const queryFormRef = ref<InstanceType<typeof ElForm>>();
97+
const userFormRef = ref<InstanceType<typeof ElForm>>();
98+
99+
// 查询相关状态
100+
const queryParams = reactive<UserPageQuery>({
101+
pageNum: 1,
102+
pageSize: 10,
103+
});
104+
105+
// 分页数据
106+
const pageData = ref<UserPageVO[]>([]);
107+
const total = ref(0);
108+
const loading = ref(false);
109+
110+
// 对话框状态
111+
const dialog = reactive({
112+
visible: false,
113+
title: "新增用户",
114+
});
115+
116+
// 表单数据 (带初始化)
117+
const formData = reactive<UserForm>({
118+
status: 1,
119+
});
60120

61-
// 6. 同级组件
62-
import ProductCard from './ProductCard.vue';
63121
```
64122

65123
---

‎src/standard/2.后端规范/README.md

+49-55
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,24 @@ com.company.project
3838

3939

4040
## 命名规范
41-
### 类/接口命名
41+
### 接口命名
42+
43+
44+
| 操作类型 | HTTP方法 | 推荐动词 | 示例路径 |
45+
|---------------|----------|------------------|-------------------------|
46+
| 获取单个 | GET | get | /users/{id} |
47+
| 获取列表 | GET | list | /users |
48+
| 分页查询 | GET | search | /users/search |
49+
| 创建资源(add) | POST | create | /users |
50+
| 全量更新(edit) | PUT | update | /users/{id} |
51+
| 局部更新 | PATCH | partialUpdate | /users/{id}/email |
52+
| 删除资源 | DELETE | delete | /users/{id} |
53+
| 关联添加 | POST | attach | /teams/{id}/members |
54+
| 批量操作 | POST | batch[Action] | /products/batch-delete |
55+
56+
57+
58+
### 对象命名
4259
| 类型 | 模式 | 示例 |
4360
|---------------|---------------------|--------------------|
4461
| REST 控制器 | `XxxController` | `UserController` |
@@ -56,66 +73,43 @@ com.company.project
5673
| 创建操作 | `createXxx` | `createUser` |
5774
| 更新操作 | `updateXxx` | `updateUser` |
5875

76+
77+
### 按钮权限标识命名
78+
79+
| 权限标识 | 模块 | 资源 | 操作 | 适用场景 | 示例按钮文案 |
80+
|---------------------------|--------|--------|-----------------|-------------------------|--------------------|
81+
| `sys:user:query` | sys | user | query | 数据查询/过滤 | 搜索用户、查看列表 |
82+
| `sys:user:add` | sys | user | add | 新增数据 | 新建用户、添加账号 |
83+
| `sys:user:edit` | sys | user | edit | 修改已有数据 | 编辑资料、修改权限 |
84+
| `sys:user:delete` | sys | user | delete | 删除数据 | 删除用户、移除账号 |
85+
| `sys:user:import` | sys | user | import | 批量数据导入 | 导入用户、批量新增 |
86+
| `sys:user:export` | sys | user | export | 数据导出为文件 | 导出Excel、下载报表|
87+
| `sys:user:reset-password` | sys | user | reset-password | 密码重置操作 | 重置密码、强制修改 |
88+
5989
---
6090

6191
## 注释规范
62-
### Swagger 接口文档
63-
```java
64-
@Operation(summary = "用户登录", description = "通过手机号+密码进行身份认证")
65-
@PostMapping("/login")
66-
public Result<UserVO> login(
67-
@Parameter(description = "登录表单", required = true)
68-
@RequestBody LoginForm form) {
69-
// ...
70-
}
71-
```
7292

73-
### 复杂逻辑注释
93+
### 类注释标准
7494
```java
75-
// 使用三斜线注释标记待优化点
76-
/// TODO: 2023-10-01 缓存穿透风险，需增加空值缓存
77-
public UserVO getUserById(Long userId) {
78-
// ...
79-
}
95+
/**
96+
* 用户控制层
97+
*
98+
* @author Ray.Hao
99+
* @since 2.9.0
100+
*
101+
* 2.9.1 - 2023-08-01 增加删除保护机制
102+
* 2.9.0 - 2023-07-15 初始版本
103+
*/
80104
```
81105

82-
---
83106

84-
## 异常处理规范
85-
### 自定义异常体系
86-
```java
87-
// 业务异常基类
88-
public class BusinessException extends RuntimeException {
89-
private final ErrorCode errorCode;
90-
91-
public BusinessException(ErrorCode errorCode) {
92-
super(errorCode.getMessage());
93-
this.errorCode = errorCode;
94-
}
95-
}
96-
97-
// 细分异常类型
98-
public class OrderNotFoundException extends BusinessException {
99-
public OrderNotFoundException() {
100-
super(ErrorCode.ORDER_NOT_FOUND);
101-
}
102-
}
103-
```
107+
| 要素 | 规范要求 |
108+
|-----------------|--------------------------------------------------------------------------|
109+
| **类描述** | 首行简明描述类职责，使用`[业务模块]+[层级类型]`结构（如：订单服务层） |
110+
| **@author** | 必须标注，多人维护时分行标注（例：`@author Ray.Hao @author Han.Helena`） |
111+
| **@since** | 必须标注，格式为`主版本.次版本.修订号`（如Spring式版本号） |
112+
| **空行规则** | 类描述与标签之间必须空一行 |
113+
114+
---
104115

105-
### 全局异常处理
106-
```java
107-
@RestControllerAdvice
108-
public class GlobalExceptionHandler {
109-
110-
@ExceptionHandler(BusinessException.class)
111-
public Result<Void> handleBusinessException(BusinessException e) {
112-
return Result.fail(e.getErrorCode());
113-
}
114-
115-
@ExceptionHandler(MethodArgumentNotValidException.class)
116-
public Result<Void> handleValidationException(MethodArgumentNotValidException e) {
117-
String message = e.getBindingResult().getAllErrors().get(0).getDefaultMessage();
118-
return Result.fail(ErrorCode.PARAM_ERROR.getCode(), message);
119-
}
120-
}
121-
```

0 commit comments

Comments
 (0)