vifo
6b83b7cbc9
- 添加前端设计文档（rui-admin、收银系统、模块打包） - 添加前端实施计划（收银后台功能完善） - 添加通用规范（API、编码、数据库、前端开发规则） - 建立文档索引和使用指南
280 lines
5.8 KiB
Markdown
280 lines
5.8 KiB
Markdown
# 编码规范
|
|
|
|
## 🎯 通用原则
|
|
|
|
1. **可读性优先** - 代码是写给人看的，顺便给机器执行
|
|
2. **DRY 原则** - Don't Repeat Yourself
|
|
3. **单一职责** - 一个类/方法只做一件事
|
|
4. **开闭原则** - 对扩展开放，对修改关闭
|
|
|
|
---
|
|
|
|
## 📝 Java 编码规范
|
|
|
|
### 命名规范
|
|
|
|
| 类型 | 规范 | 示例 |
|
|
|------|------|------|
|
|
| 类名 | 大驼峰 | `UserService`, `OrderController` |
|
|
| 方法名 | 小驼峰 | `getUserById()`, `createOrder()` |
|
|
| 变量名 | 小驼峰 | `userName`, `orderList` |
|
|
| 常量 | 全大写下划线 | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
|
|
| 包名 | 全小写 | `com.rui.service.user` |
|
|
|
|
### 代码格式
|
|
|
|
```java
|
|
// 正确的类定义
|
|
@Service
|
|
public class UserServiceImpl implements IUserService {
|
|
|
|
private final UserMapper userMapper;
|
|
private final RedisUtil redisUtil;
|
|
|
|
// 构造器注入（推荐）
|
|
public UserServiceImpl(UserMapper userMapper, RedisUtil redisUtil) {
|
|
this.userMapper = userMapper;
|
|
this.redisUtil = redisUtil;
|
|
}
|
|
|
|
// 方法注释
|
|
/**
|
|
* 根据ID获取用户信息
|
|
* @param userId 用户ID
|
|
* @return 用户信息
|
|
*/
|
|
@Override
|
|
public UserDTO getUserById(Long userId) {
|
|
// 先查缓存
|
|
UserDTO user = redisUtil.get("user:" + userId);
|
|
if (user != null) {
|
|
return user;
|
|
}
|
|
|
|
// 再查数据库
|
|
User entity = userMapper.selectById(userId);
|
|
if (entity == null) {
|
|
throw new BizException("用户不存在");
|
|
}
|
|
|
|
// 转换并缓存
|
|
user = convertToDTO(entity);
|
|
redisUtil.set("user:" + userId, user, 3600);
|
|
|
|
return user;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 注释规范
|
|
|
|
```java
|
|
/**
|
|
* 用户服务实现类
|
|
*
|
|
* @author pigeon
|
|
* @since 2024-01-01
|
|
*/
|
|
@Service
|
|
public class UserServiceImpl {
|
|
|
|
/**
|
|
* 获取用户详情
|
|
*
|
|
* @param userId 用户ID，不能为空
|
|
* @return 用户详情DTO
|
|
* @throws BizException 用户不存在时抛出
|
|
*/
|
|
public UserDetailDTO getDetail(Long userId) {
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🌐 TypeScript/Vue 编码规范
|
|
|
|
### 命名规范
|
|
|
|
| 类型 | 规范 | 示例 |
|
|
|------|------|------|
|
|
| 组件名 | 大驼峰 | `UserTable.vue`, `OrderForm.vue` |
|
|
| 组合式函数 | use前缀 | `useUser()`, `useOrder()` |
|
|
| 类型定义 | 大驼峰 | `UserDTO`, `OrderFormData` |
|
|
| 常量 | 全大写下划线 | `API_BASE_URL`, `PAGE_SIZE` |
|
|
| 变量/函数 | 小驼峰 | `userList`, `getUserList()` |
|
|
|
|
### 组件规范
|
|
|
|
```vue
|
|
<script setup lang="ts">
|
|
/**
|
|
* 用户管理组件
|
|
*
|
|
* @description 展示用户列表，支持增删改查
|
|
* @author pigeon
|
|
*/
|
|
import { ref, onMounted } from 'vue'
|
|
import type { UserDTO } from '@/types'
|
|
|
|
// Props 定义
|
|
interface Props {
|
|
deptId?: number
|
|
}
|
|
|
|
const props = withDefaults(defineProps<Props>(), {
|
|
deptId: undefined
|
|
})
|
|
|
|
// Emits 定义
|
|
const emit = defineEmits<{
|
|
refresh: []
|
|
}>()
|
|
|
|
// 响应式数据
|
|
const userList = ref<UserDTO[]>([])
|
|
const loading = ref(false)
|
|
|
|
// 方法
|
|
async function loadUserList() {
|
|
loading.value = true
|
|
try {
|
|
const res = await userApi.getList({ deptId: props.deptId })
|
|
userList.value = res.data
|
|
} finally {
|
|
loading.value = false
|
|
}
|
|
}
|
|
|
|
// 生命周期
|
|
onMounted(() => {
|
|
loadUserList()
|
|
})
|
|
</script>
|
|
```
|
|
|
|
---
|
|
|
|
## 🗄️ 数据库规范
|
|
|
|
### 命名规范
|
|
|
|
| 类型 | 规范 | 示例 |
|
|
|------|------|------|
|
|
| 表名 | 下划线、复数 | `sys_user`, `cashier_order` |
|
|
| 字段名 | 下划线 | `user_name`, `created_at` |
|
|
| 索引名 | idx_前缀 | `idx_user_name` |
|
|
| 外键 | fk_前缀 | `fk_order_user` |
|
|
|
|
### 必备字段
|
|
|
|
```sql
|
|
-- 所有表必须包含以下字段
|
|
CREATE TABLE example_table (
|
|
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
|
|
-- 业务字段
|
|
name VARCHAR(100) NOT NULL COMMENT '名称',
|
|
|
|
-- 审计字段（由框架自动填充）
|
|
create_by VARCHAR(64) COMMENT '创建者',
|
|
create_time DATETIME COMMENT '创建时间',
|
|
update_by VARCHAR(64) COMMENT '更新者',
|
|
update_time DATETIME COMMENT '更新时间',
|
|
deleted TINYINT DEFAULT 0 COMMENT '删除标志（0-正常，1-删除）',
|
|
tenant_id BIGINT COMMENT '租户ID',
|
|
|
|
-- 索引
|
|
INDEX idx_name (name)
|
|
) COMMENT='示例表';
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 安全规范
|
|
|
|
1. **SQL 注入防护** - 使用 MyBatis 参数绑定，禁止字符串拼接 SQL
|
|
2. **XSS 防护** - 前端转义输出，后端校验输入
|
|
3. **敏感信息** - 密码必须加密存储，日志中禁止输出敏感信息
|
|
4. **接口鉴权** - 所有接口必须校验权限（白名单除外）
|
|
|
|
---
|
|
|
|
## 🧪 测试规范
|
|
|
|
### Java 测试
|
|
|
|
```java
|
|
@SpringBootTest
|
|
class UserServiceTest {
|
|
|
|
@Autowired
|
|
private IUserService userService;
|
|
|
|
@Test
|
|
@DisplayName("根据ID查询用户-正常情况")
|
|
void getUserById_Success() {
|
|
// Given
|
|
Long userId = 1L;
|
|
|
|
// When
|
|
UserDTO user = userService.getUserById(userId);
|
|
|
|
// Then
|
|
assertThat(user).isNotNull();
|
|
assertThat(user.getId()).isEqualTo(userId);
|
|
}
|
|
|
|
@Test
|
|
@DisplayName("根据ID查询用户-用户不存在")
|
|
void getUserById_NotFound() {
|
|
// Given
|
|
Long userId = 999L;
|
|
|
|
// Then
|
|
assertThrows(BizException.class, () -> {
|
|
userService.getUserById(userId);
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Git 提交规范
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
### Type 类型
|
|
|
|
| 类型 | 说明 |
|
|
|------|------|
|
|
| feat | 新功能 |
|
|
| fix | 修复 bug |
|
|
| docs | 文档更新 |
|
|
| style | 代码格式（不影响功能） |
|
|
| refactor | 重构 |
|
|
| test | 测试相关 |
|
|
| chore | 构建/工具相关 |
|
|
|
|
### 示例
|
|
|
|
```bash
|
|
feat(cashier): 添加订单退款功能
|
|
|
|
- 支持部分退款
|
|
- 支持原路退回
|
|
- 添加退款记录表
|
|
|
|
Closes #123
|
|
```
|
|
|
|
---
|
|
|
|
> **最后提醒**：编码规范是为了团队协作，请务必遵守！ |