microwind/ai-skills/consistency-principle

// ❌ 不一致的命名
public class UserService {
    public User getUser(Long id);           // get
    public Order fetchOrder(Long id);       // fetch
    public Product retrieveProduct(Long id); // retrieve
    public Invoice findInvoice(Long id);    // find
    // 四个不同的词表达同一含义
}
 
// ✅ 一致命名
public class UserService {
    public User findById(Long id);
}
public class OrderService {
    public Order findById(Long id);
}
public class ProductService {
    public Product findById(Long id);
}

# ❌ 不一致的错误处理
class UserService:
    def create_user(self, data):
        return None  # 失败返回 None
class OrderService:
    def create_order(self, data):
        raise ValueError("创建失败")  # 失败抛异常
class PaymentService:
    def create_payment(self, data):
        return {"success": False, "error": "失败"}  # 失败返回错误对象
# ✅ 一致的错误处理策略
# 团队约定：业务异常统一抛自定义异常
class UserService:
    def create_user(self, data):
        if not data.get("email"):
            raise ValidationError("邮箱不能为空")
class OrderService:
    def create_order(self, data):
        if not data.get("items"):
            raise ValidationError("订单项不能为空")

// ✅ 所有 API 端点遵循相同的模式
// 请求格式一致
interface ApiResponse<T> {
    code: number;
    data: T;
    message: string;
}
// 错误处理一致
app.get('/api/users/:id', async (req, res) => {
    const user = await userService.findById(req.params.id);
    if (!user) return res.status(404).json({ code: 404, data: null, message: '用户不存在' });
    return res.json({ code: 200, data: user, message: 'ok' });
});
app.get('/api/orders/:id', async (req, res) => {
    const order = await orderService.findById(req.params.id);
    if (!order) return res.status(404).json({ code: 404, data: null, message: '订单不存在' });
    return res.json({ code: 200, data: order, message: 'ok' });
});

□ 相同操作在不同模块中用相同的方法名
□ 错误处理策略全项目统一
□ API 响应格式统一
□ 日志格式和级别使用规范一致
□ 目录结构在各模块间一致
□ 数据库命名规范一致（snake_case vs camelCase）
□ 时间格式统一（UTC vs 本地时区）
□ 配置方式统一（环境变量 vs 配置文件）

✅ 有充分理由时可以例外：
- 性能瓶颈要求特殊实现
- 第三方库强制了不同的模式
- 新的最佳实践明显优于现有惯例
 
⚠️ 打破一致性时：
- 记录原因（ADR 或代码注释）
- 通知团队
- 评估是否应该全局迁移到新模式