Backend Silk:共享后端标准
扮演一位编写简单、生产级代码的资深 Python 后端工程师。此技能旨在防止的两个失败是错误的结构(逻辑放错层、无用的文件)和过度设计(在应用尚未正常工作前进行抽象)。第三个更隐蔽的失败同样代价高昂:一次变更或重构在无声无息中丢弃了之前正常工作的行为。
配套技能
命名:*-spider 技能用于构建特定类型的项目;*-silk 技能是每个蜘蛛都会使用的共享标准。此技能包含所有后端共享的原则。请同时加载匹配的配套技能:
| 情况 | 同时使用 |
|---|---|
| Flask / FastAPI / Django 项目 | flask-spider / fastapi-spider / django-spider |
| Node.js / Express 项目 | node-spider(此处规则适用;Python 代码示例采用 Python) |
| MCP 服务器或 MCP 客户端 | mcp-spider |
| PostgreSQL、MySQL、SQLite(SQLAlchemy、Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM、嵌入、向量存储、RAG | rag-spider |
框架技能决定框架机制;此技能决定原则。如果两者似乎冲突,则遵循框架技能的语法和此技能的结构。
修改代码前
- 先阅读实际代码。 检查文件夹结构、模型、配置以及你要更改的文件。切勿猜测字段名、函数签名、文件名或导入路径;请阅读它们。(一个猜错的
date而非实际的expense_date曾一次性破坏了 schema、辅助函数和响应。)当不确定已安装库的工作方式时,请检查其实际 API,而非假定。 - 首先确定路由。 对于某个功能,在实现之前,先列出每个端点(方法、路径、请求、响应、状态码、认证)。
- 范围源自需求。 只构建问题陈述所需要的内容。额外的端点、分析、缓存、速率限制、重新排序、成本跟踪、无人要求的下载/搜索端点:在一行中提一句“可能以后需要”,不要构建。
- 保留正常工作行为。 重写函数时,列出它当前的功能(过滤器、分页、验证、日志、响应字段),并确保新版本仍然全部实现。
分层
routes -> helpers -> services -> database / external systems
| |
utils utils
| 文件夹 | 拥有 | 不得包含 |
|---|---|---|
routes/(Flask 蓝图、FastAPI 路由、Django views.py + urls.py、MCP tools/) | URL、方法、认证依赖/装饰器、状态码、响应模型、对辅助函数的一次调用 | 业务逻辑、查询、验证代码、try/except、日志 |
helpers/ | 一个功能的业务逻辑,类似于控制器:超出 schema 的验证、所有权检查、特定功能的查询和过滤器、服务编排、将预期的失败映射为 HTTP 错误、构建响应 | 打开/关闭数据库会话、提交/回滚、创建 LLM 或 SDK 客户端 |
services/ | 每个外部系统或基础设施组件一个:数据库连接和通用 CRUD(db_service.py)、LLM、嵌入、向量存储、PDF、电子邮件、其他仓库的 API | 特定功能的业务规则、HTTP 知识(HTTPException、状态码)、对辅助函数的调用 |
utils/ | 被多个模块复用的基于类的代码:LogUtils、ErrorHandlers、AuthUtils、纯转换器 | 仅被一个功能使用的代码、外部 API 调用 |
schemas/ | Pydantic 请求/响应模型(Django:serializers.py) | 数据库模型 |
models/ | 持久化模型 | 业务逻辑 |
prompts/ | 作为代码的提示模板(仅当使用 LLM 时) | .env 中的提示 |
config.py | 从 .env 加载的一个设置对象 | 逻辑 |
表中衍生出的规则:
- 方向是单向的。 路由调用辅助函数,辅助函数调用服务。服务绝不调用辅助函数;工具函数绝不调用辅助函数。
- 数据库分离。 辅助函数构建功能查询(过滤器、搜索、所有权);数据库服务执行这些查询并拥有连接、会话、提交和回滚的责任。详情请见
sql-silk/mongodb-silk。对于 Django,ORM 即是数据库层,因此不存在db_service。 - 没有无作为的传递层。 如果辅助函数仅转发给服务,则删除该辅助函数并直接调用服务。每个文件都必须有其存在的价值。
- 工具函数 vs 辅助函数。 在多个地方使用 →
utils/。仅被一个功能使用 → 该功能的辅助函数。 - 在真正需要时才创建文件夹和文件,而不是预先创建。一个函数永远不足以证明一个新文件夹(
errors/、exceptions.py、core/)的合理性;将其添加到适合的现有类中。 - 命名:
<domain>_routes.py(包含<domain>_router,或在 Flask 中为<domain>_bp)、<domain>_helper.py→XHelper、<domain>_service.py→XService、<domain>_schema.py、<domain>_utils.py→XUtils、<name>_prompt.py→NAME_PROMPT。类名必须与其所在的文件夹匹配(在helpers/中的class ExpenseService是错误的)。
完整的文件夹角色和起始树结构:references/architecture.md。
代码规则
- 基于类的模块。 辅助函数、服务和工具函数都是类。对于无状态代码使用
@staticmethod/@classmethod,仅当类持有依赖(例如注入的会话或客户端)时才使用实例。路由文件和 Django 的urls.py保持模块级别。不要在没有两个实际实现的情况下强制使用继承、抽象基类或接口。 - 函数保持在 40-50 行左右。 将长函数拆分为同一类中有意义的方法(例如
list_expenses→parse_filter_parameters+apply_expense_filters),而不是任意的代码块。 - 函数名不能以
_开头。函数内部不得定义函数。 使用显式调用(例如app.add_exception_handler(...))注册处理程序,而不是嵌套的装饰函数。 - 所有导入都在文件顶部,分组为:标准库 → 第三方库 →
app.*。通过将代码移动到正确的模块来修复循环导入,而不是在函数内部进行导入。唯一接受的例外是在create_app()内部导入 Flask 蓝图。 - 使用成熟库而非手写逻辑:
password-validator、email-validator/EmailStr、PyJWT、bcrypt、LangChain 加载器和分割器、httpx。 - 只验证一次。 如果 Pydantic schema 已经强制执行了规则,不要在辅助函数中重复检查。
- 不要在单个请求中重复计算同一件事,并且要快速失败。 在较昂贵的检查之前执行廉价检查(在进行 bcrypt 哈希之前检查电子邮件重复)。
- 没有硬编码的配置:URL、模型名称、限制、top_k、temperature 和密钥来自
config.py。 - 没有死代码:删除未使用的函数、未使用的导入、空的占位符文件和
startapp遗留物。 - 类型提示和一行文档字符串用于每个类和公共方法。仅在原因不明显时添加注释。
- 绝不吞没异常。 捕获你可以对其采取行动的具体异常;让其余的异常到达全局处理程序。
过度设计检查
在添加文件、类、层、依赖或模式之前,请问:当前需求是否需要它,并且现有代码是否已经实现了它?以下所有这些都曾被构建然后被删除:
- 在应用运行之前的 pydantic-settings 或验证框架(一个冻结的 dataclass 配置就足够了)
- 为单一错误新建的异常模块或类
- 仅调用服务的辅助函数
- 在你拥有的两个服务之间使用 RS256 密钥对(一个 HS256 共享密钥就足够)
- 存储的派生值(当输入+输出都存在时的
total_tokens) - 两个集合或表,而一个内嵌列表即可工作的场景
- 长的提示和长的工具描述
当几种设计都可行时,选择最简单但仍然保证生产安全的一种。
请求和响应模式(摘要)
- 每个端点使用请求模式验证其主体和查询参数,拒绝未知字段和服务器拥有的字段;验证后的代码仅使用已验证的对象。
- 每个成功的响应都基于响应模式构建:资源本身(
XResponse)、列表{"items", "page", "page_size", "total", "total_pages"}或操作结果模式(TokenResponse)。没有信封对象,也没有在处理程序中组装的对象字面量。 - 状态码表示成功和失败:200 表示读取/更新,201 表示创建,204 表示删除且无响应体,错误使用
ErrorResponse。从不使用 200 表示失败。
完整的契约以及不同框架中模式的位置:references/api-design.md。
错误处理(摘要)
- 每个错误响应都有一个统一格式,来源于
assets/common_schema.py:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(details仅在有字段错误时出现) - 服务抛出普通异常或库异常;辅助函数对预期情况抛出 HTTP 错误;
utils/error_handlers.py中一个ErrorHandlers类负责映射依赖错误并将其他所有错误捕获为 500。 - 状态码:400 输入错误,401 未认证,404 缺失或另一用户的记录,409 重复,413 过大,422 schema 验证,424 我们自己的依赖不可用(数据库、向量存储),429 上游速率限制,502 上游返回错误,503 其他服务不可达,504 上游超时,500 意外错误。绝不使用 200 表示失败。
- 用户只看到简短的安全消息,绝不显示回溯、主机、连接字符串或密钥。
边缘情况检查清单和处理程序模式:references/errors-and-edge-cases.md。仓库间调用:references/cross-repo-communication.md。
日志(摘要)
一个 LogUtils 类(assets/log_utils.py)在启动时根据 .env 中的 LOG_LEVEL 和 LOG_TO_FILE 配置一次;其他所有模块仅执行 logger = LogUtils.get_logger(__name__)。格式 %(asctime)s | %(levelname)s | %(name)s | %(message)s,消息格式为 Event | key=value,不包含密钥或个人数据,每个失败只记录一次。详情:references/logging.md。
配置与安全(摘要)
config.py包含一个从.env加载的冻结 dataclass(assets/config.py);.env.example提交到仓库并带有占位符和注释(assets/env.example),.env绝不提交(assets/gitignore)。- 密码:仅在注册时使用
password-validator策略,使用 bcrypt/werkzeug 哈希,登录时给出通用提示“无效的电子邮件或密码。” - JWT:密钥来自
.env,用户 ID 仅从已验证的令牌中获取,绝不从请求体中获取。 - 每个查询都限定在当前用户范围内;其他用户的记录返回 404。
详情:references/security.md。API 约定(方法、分页、过滤、搜索参数):references/api-design.md。
Git 和测试(摘要)
- 绝不提交:
.env、密钥、凭据、上传文件、向量数据、本地数据库、日志、虚拟环境、生成的报告。数据库迁移与产生它们的模型更改一起提交。 - 提交信息遵循 Conventional Commits 规范(
feat:、fix:、refactor:、chore:、test:、docs:、perf:),每次提交只处理一个关注点,每个仓库只有一个提交。 - 测试覆盖关键路径:认证、用户间所有权、验证、错误响应、依赖失败(模拟)。外部服务(LLM、其他仓库)被模拟。
- 评估(金数据集、评估脚本、报告)仅在明确要求时存在;参见
rag-spider/mcp-spider。
详情:references/git-and-testing.md。
代码检查清单
- 分层得到遵守;没有无作为的传递文件;类名与文件夹匹配
- 没有以下划线开头或嵌套的函数;导入在文件顶部;函数 ≤ ~50 行
- 现有行为已保留(过滤器、分页、验证、响应字段)
- 每个端点都有请求模式和响应模式;没有临时构建的响应对象
- 来自
references/errors-and-edge-cases.md的边缘情况已使用正确的状态码处理 - 新设置在
config.py和.env.example中;没有硬编码;代码或日志中没有密钥 - 在合适的地方添加了日志记录,并使用了正确的级别
- 没有留下未使用的导入或死代码
参考文件(仅在需要时阅读)
| 文件 | 何时阅读 |
|---|---|
references/architecture.md | 创建项目、添加功能文件夹、不确定代码归属时 |
references/errors-and-edge-cases.md | 编写端点、错误处理程序或审查失败路径时 |
references/cross-repo-communication.md | 一个服务调用另一个仓库、MCP 服务器或外部 API 时 |
references/logging.md | 设置或审查日志时 |
references/security.md | 认证、密码、JWT、上传、密钥、CORS |
references/api-design.md | 设计端点、请求/响应模式、分页、过滤器、搜索时 |
references/git-and-testing.md | 提交、PR 描述、哪些内容绝不提交、测试、调试方法 |
资产文件(复制到项目中并适应)
选择性地复制模板:只保留该项目当前使用的部分(.gitignore 的章节、.env.example 的键、配置字段)。项目不具备的功能所遗留的行会成为冗余并误导下一位阅读者。
| 文件 | 成为 |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore(“始终”部分加上仅适用且被标记的部分) |