rui-docs/standards/coding-standards.md

编码规范

🎯 通用原则

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

代码格式

// 正确的类定义
@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;
    }
}

注释规范

/**
 * 用户服务实现类
 * 
 * @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()

组件规范

<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

必备字段

-- 所有表必须包含以下字段
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 测试

@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	构建/工具相关

示例

feat(cashier): 添加订单退款功能

- 支持部分退款
- 支持原路退回
- 添加退款记录表

Closes #123

---

最后提醒：编码规范是为了团队协作，请务必遵守！