Community编程与开发github.com

backend-silk

编码技能。为 Python(Flask、FastAPI、Django、FastMCP)和 Node.js(Express)后端与 API 项目提供的共享工程标准。涵盖项目结构、路由-辅助-服务分层、基于类的代码规则、错误处理与状态码、边缘情况、日志、.env 配置、认证与数据所有权、仓库间通信、Git 卫生与测试。在创建、扩展、调试、重构或审查任何 Python 后端、REST API、MCP 服务器或 RAG 后端时使用。

backend-silk 是什么?

Backend Silk 是一种编码技能,为后端和 API 项目提供一套共享的工程标准,适用于 Python(Flask、FastAPI、Django、FastMCP)和 Node.js(Express)项目。它围绕一个严格的分层架构组织代码:路由层(routes)→ 辅助层(helpers)→ 服务层(services)→ 数据库/外部系统,并规定了每层的职责以及禁止包含的内容,旨在防止错误的结构和过度设计。该技能强调基于类的模块、简洁的函数(约40-50行)、具体的错误处理(使用统一错误响应格式和恰当的状态码)以及安全的配置管理(.env + config.py)。此外,它还涵盖了跨仓库通信、Git 规范与测试原则,并提供了可参照的资产文件(如日志工具、通用模式)和参考文档,确保代码的可维护性、健壮性以及团队协作的一致性。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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
MongoDBmongodb-silk
LLM、嵌入、向量存储、RAGrag-spider

框架技能决定框架机制;此技能决定原则。如果两者似乎冲突,则遵循框架技能的语法和此技能的结构。

修改代码前

  1. 先阅读实际代码。 检查文件夹结构、模型、配置以及你要更改的文件。切勿猜测字段名、函数签名、文件名或导入路径;请阅读它们。(一个猜错的 date 而非实际的 expense_date 曾一次性破坏了 schema、辅助函数和响应。)当不确定已安装库的工作方式时,请检查其实际 API,而非假定。
  2. 首先确定路由。 对于某个功能,在实现之前,先列出每个端点(方法、路径、请求、响应、状态码、认证)。
  3. 范围源自需求。 只构建问题陈述所需要的内容。额外的端点、分析、缓存、速率限制、重新排序、成本跟踪、无人要求的下载/搜索端点:在一行中提一句“可能以后需要”,不要构建。
  4. 保留正常工作行为。 重写函数时,列出它当前的功能(过滤器、分页、验证、日志、响应字段),并确保新版本仍然全部实现。

分层

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。

代码规则

  1. 基于类的模块。 辅助函数、服务和工具函数都是类。对于无状态代码使用 @staticmethod/@classmethod,仅当类持有依赖(例如注入的会话或客户端)时才使用实例。路由文件和 Django 的 urls.py 保持模块级别。不要在没有两个实际实现的情况下强制使用继承、抽象基类或接口。
  2. 函数保持在 40-50 行左右。 将长函数拆分为同一类中有意义的方法(例如 list_expenses → parse_filter_parameters + apply_expense_filters),而不是任意的代码块。
  3. 函数名不能以 _ 开头。函数内部不得定义函数。 使用显式调用(例如 app.add_exception_handler(...))注册处理程序,而不是嵌套的装饰函数。
  4. 所有导入都在文件顶部,分组为:标准库 → 第三方库 → app.*。通过将代码移动到正确的模块来修复循环导入,而不是在函数内部进行导入。唯一接受的例外是在 create_app() 内部导入 Flask 蓝图。
  5. 使用成熟库而非手写逻辑:password-validator、email-validator/EmailStr、PyJWT、bcrypt、LangChain 加载器和分割器、httpx。
  6. 只验证一次。 如果 Pydantic schema 已经强制执行了规则,不要在辅助函数中重复检查。
  7. 不要在单个请求中重复计算同一件事,并且要快速失败。 在较昂贵的检查之前执行廉价检查(在进行 bcrypt 哈希之前检查电子邮件重复)。
  8. 没有硬编码的配置:URL、模型名称、限制、top_k、temperature 和密钥来自 config.py。
  9. 没有死代码:删除未使用的函数、未使用的导入、空的占位符文件和 startapp 遗留物。
  10. 类型提示和一行文档字符串用于每个类和公共方法。仅在原因不明显时添加注释。
  11. 绝不吞没异常。 捕获你可以对其采取行动的具体异常;让其余的异常到达全局处理程序。

过度设计检查

在添加文件、类、层、依赖或模式之前,请问:当前需求是否需要它,并且现有代码是否已经实现了它?以下所有这些都曾被构建然后被删除:

  • 在应用运行之前的 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.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore(“始终”部分加上仅适用且被标记的部分)

相关技能