claude-backend-skilllisted

# 后端决策逻辑 这份规则描述的是在处理后端相关任务时的核心决策逻辑。后端系统的核心问题是：如何在保证数据正确性和系统稳定性的前提下，高效地处理来自外部的请求并管理系统状态。这套规则涵盖 API 设计、数据建模、业务逻辑组织、安全策略和可观测性，每一部分都是后端工程质量的关键支柱。 --- ## 一、API 设计的第一性原理 ### 1.1 API 是契约，不是实现 API 一旦发布并有调用方依赖，修改它的成本非常高。调用方需要感知到变化并做出相应调整，这需要协调和时间。因此 API 的设计必须在实现之前经过充分思考，而不是先快速实现一个版本再迭代优化。 设计阶段需要回答的问题：这个 API 解决的是什么问题，调用方需要的最小信息集合是什么，这个 API 的边界在哪里（它不应该做什么），以及这个 API 在未来可能的扩展方向是什么。 ### 1.2 一致性是 API 最重要的特征 调用方在学会一个端点的使用方式之后，应该能够对其他端点有准确的预期。一致性体现在：端点命名的模式（动词还是名词，复数还是单数）、请求参数的位置和格式（path 参数 vs query 参数 vs 请求体）、响应结构（成功时的数据格式、失败时的错误格式）、HTTP 状态码的使用方式（200、201、400、401、403、404、500 各自代表什么）。 ### 1.3 向后兼容优先于完美设计 在需要修改已发布 API 时，优先选择向后兼容的修改方式：添加新的可选字段（调用方忽略它），新增端点（旧端点继续工作），扩展枚举值范围（调用方遇到未知值时优雅降级）。 必须做破坏性修改时，使用版本控制：在 URL 路径或请求头中标注版本，维护旧版本一段时间并给调用方足够的迁移时间，在下线旧版本前发出充分的提前通知。 ```mermaid flowchart TD A[需要修改已发布的 API] --> B{是否是破坏性修改} B -- 否，可向后兼容 --> C[直接添加新字段或新端点] B -- 是，破坏性修改 --> D[评估修改的必要性] D --> E[发布新版本 API] E --> F[通知调用方迁移] F --> G[���护旧版本一段时间] G --> H[在约定时间后下线旧版本] C --> I[通知调用方新能力可用] ``` ### 1.4 错误响应的完整性 错误响应和成功响应一样重要。一个好的错误响应包含：机器可读的错误码（让调用方能够区分不同类型的错误并做出不同的处理）、人类可读的错误描述（让开发者能够快速理解出了什么问题）、以及在适当时候包含字段级别的验证错误（让调用方能够将错误定位到具体的输入字段）。 --- ## 二、数据库设计的核心思维 ### 2.1 数据模型是最难修复的错误 代码可以重写，但数据模型的变更需要同时迁移存量数据，在生产环境中这是有风险的操作。因此数据模型的设计需要比代码设计更谨慎，需要在实现之前充分考虑查询模式、数据关系和未来的扩展方向。 设计数据模型时需要同时考虑：这些数据如何被写入，最常见的查询模式是什么，数据之间的关系是什么，哪些字段会随时间演变，以及历史数据的保留需求。 ### 2.2 范式化与反范式化的权衡 完全范式化减少冗余，保证数据一致性，但查询需要多表连接，在高频查询场景下性能差。反范式化（冗余存储某些字段）提升查询性能，但增加了数据一致性维护的复杂度——每次更新源数据时，所有冗余副本也需要同步更新。 选择依据