技能使用指南

backend-dev-guidelines（后端开发指南）Skill 是什么？能解决哪些后端开发问题？

backend-dev-guidelines（后端开发指南）Skill 把分层架构、BaseController、Sentry、Zod、unifiedConfig 等后端规范固化为 AI 可执行上下文，让 Node.js/Express/TypeScript 微服务代码天然合规。了解它的安装方式、七条核心原则、竞品对比与典型场景，快速统一团队写法、降低 Review 返工。

后端开发指南Skillbackend-dev-guidelines
35 个章节 约 22 分钟阅读 AI 智能生成

后端开发指南Skill：让 AI 按统一规范生成 Node.js 微服务代码

  • 一句话定位：这不是一个"写代码"的工具，而是一份会被 AI 自动加载的后端工程规范，让你和 AI 写出的每一行 Node.js/Express/TypeScript 代码都符合同一套分层架构。
  • 核心机制：把「路由→控制器→服务→仓库」的分层架构、BaseController 模式、Sentry 错误上报、Zod 输入校验、unifiedConfig 配置管理等 7 条硬规则，固化成 AI 可读取的技能文件。
  • 自动激活：当你让 AI 创建路由、写控制器、接 Prisma、加中间件、做输入校验时，技能会自动触发，不需要每次重复交代规范。
  • 渐进披露：主文件控制在 500 行以内，配套 11 个资源文件，按需深入架构、验证、监控、测试、配置等细分主题。
  • 最大价值：把"团队里只有资深工程师知道的写法"变成"AI 每次都默认这么写"，显著降低 Code Review 返工率与新人上手成本。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
技能中文名 后端开发指南
技能英文名 backend-dev-guidelines
技能ID 12244
适用技术栈 Node.js + Express + TypeScript 微服务
关联生态 Prisma、Sentry、Zod、unifiedConfig、依赖注入
技能状态 完成（主文件 < 500 行，配套 11 个资源文件）

它到底解决什么问题？

在真实的后端团队里，最常见的问题不是"不会写"，而是"每个人写得都不一样"：

  • 有人在路由文件里直接堆两百行业务逻辑，控制器形同虚设；
  • 有人到处写 process.env.XXX，线上环境改一个超时时间要重新发版；
  • 有人用 console.log 打日志，线上报错后翻遍日志文件也定位不到根因；
  • 有人跳过输入校验，接口被脏数据打穿；
  • 有人直接在服务层调 Prisma，数据访问逻辑散落各处，改表结构时牵一发动全身。

这些都不是"能力问题"，而是"规范没有被执行"的问题。后端开发指南技能的作用，就是把团队的后端架构规范变成 AI 的默认上下文——当 AI 帮你生成代码时，它天然遵守分层架构、天然使用 BaseController、天然把错误送进 Sentry，而不是每次都要你在对话开头粘贴一大段"请注意我们团队规范如下……"。

一键安装的思路与步骤

安装的具体命令、入口地址与账号要求由各技能平台定义，请以官方说明为准。通用流程如下：

  1. 确认前提条件

    • 你的 AI 编程环境支持"技能 / Skill"机制（可在技能市场、插件中心或项目配置目录中加载自定义技能）；
    • 你正在维护或即将创建 Node.js + Express + TypeScript 微服务项目；
    • 项目已确定或准备引入 Prisma、Sentry、Zod 中的部分或全部依赖（未使用时技能中的对应章节可跳过）。

  2. 找到并安装技能

    • 在技能平台内搜索技能英文名 backend-dev-guidelines，或直接使用技能ID 12244 定位；
    • 按平台提供的安装入口一键安装（通常为"安装 / 添加到工作区 / 启用"按钮，具体名称以官方说明为准）。

  3. 确认技能已加载

    • 安装后查看技能列表或项目配置，确认 backend-dev-guidelines 处于启用状态；
    • 技能的主文件与 11 个资源文件应可见，包括架构总览、路由与控制器、服务与仓库、验证模式、Sentry 与监控、中间件指南、数据库模式、配置管理、异步与错误、测试指南、完整示例。

  4. 验证是否真正生效

    • 在对话中提出一个明确的后端开发请求，例如「帮我在用户服务里新增一个注册接口」，观察 AI 的输出是否：
      • 把业务逻辑放在控制器 / 服务层，而不是塞进路由；
      • 控制器继承 BaseController；
      • 使用 Zod 定义请求体校验模式；
      • 错误处理走 handleError 并上报 Sentry；
      • 配置读取来自 unifiedConfig 而非 process.env。
    • 只要上述特征出现，说明技能已被正确激活。

  5. 建立长期习惯

    • 把"新增后端功能"的请求固定为一句自然语言描述即可，不必再手写规范说明；
    • 团队内新成员入职时，把该技能随项目一起下发，等于给每个人配了一位"架构守门员"。

该技能的主要功能和特点

1. 强制分层架构，职责边界清晰

技能内置了明确的分层调用链：

HTTP 请求 → 路由 → 控制器 → 服务 → 仓库 → 数据库（Prisma）

并配套一条硬性原则：路由只负责路由，控制器只负责请求处理。这样 AI 生成代码时不会把业务逻辑随手塞进 router.post() 的回调里。

2. BaseController 统一请求处理范式

所有控制器都要求继承 BaseController，成功响应走 handleSuccess，异常走 handleError。好处是：状态码规范统一、错误格式统一、日志与上报行为统一，前端不用为每个接口写不同的错误解析逻辑。

3. 七条核心原则，覆盖最容易踩坑的地方

序号 原则 反面写法
1 路由仅路由，控制器控制 在路由里写业务逻辑
2 所有控制器继承 BaseController 每个控制器自己拼状态码
3 所有错误上报 Sentry 只写 console.log
4 配置只用 unifiedConfig 到处 process.env
5 所有输入用 Zod 校验 直接信任 req.body
6 数据访问走仓库模式 服务层直接调 Prisma
7 需要完整的单元 + 集成测试 只测"能不能跑通"

4. 目录结构与命名约定标准化

技能给出了 service/src/ 下的标准目录树（config、controllers、services、repositories、routes、middleware、types、validators、utils、tests、instrument.ts、app.ts、server.ts），并明确了命名风格：

  • 控制器用 PascalCase：UserController.ts
  • 服务用 camelCase：userService.ts
  • 路由用 camelCase + Routes：userRoutes.ts
  • 仓库用 PascalCase + Repository：UserRepository.ts

这一点看似琐碎，但对多服务并行的团队来说，能直接减少大量"文件在哪、叫什么"的沟通成本。

5. 渐进披露设计，主文件轻量、资源文件丰富

主文件控制在 500 行以内，避免一次性把全部细节塞进 AI 上下文；同时提供 11 个资源文件，按需深入：

想解决的问题 对应资源文件
理解整体架构与请求生命周期 architecture-overview.md
创建路由 / 控制器 routing-and-controllers.md
组织业务逻辑、依赖注入 services-and-repositories.md
输入校验与 DTO 模式 validation-patterns.md
Sentry 初始化与性能监控 sentry-and-monitoring.md
认证、审计、错误边界中间件 middleware-guide.md
PrismaService、事务与查询优化 database-patterns.md
unifiedConfig 与环境密钥 configuration.md
异步模式与自定义错误 async-and-errors.md
单元 / 集成测试与覆盖率 testing-guide.md
完整示例与重构指南 complete-examples.md

6. 内置反模式清单，主动拦截坏味道

技能明确列出了六类需要避免的反模式：路由内写业务逻辑、直接用 process.env、缺少错误处理、无输入校验、到处直接调 Prisma、用 console.log 代替 Sentry。这意味着 AI 在被要求写代码时，会主动规避这些写法，而不是等你复查时才发现。

7. 自带"检查清单"，可当交付前的自检表

技能提供了两份清单：新后端功能检查清单和新微服务检查清单。前者逐项核对路由、控制器、服务、仓库、验证、Sentry、测试、配置；后者覆盖目录结构、instrument.ts、unifiedConfig、BaseController、中间件栈、错误边界、测试框架。即便不依赖 AI，这两份清单本身就可以直接贴进团队的 PR 模板。

和普通工具有什么不一样？

普通静态检查工具（ESLint 等）只能发现"语法与风格"问题，无法判断"这个业务逻辑该不该写在路由里"；而官方框架文档是只读的、需要人去翻阅的。这个技能的差异在于：规范是被 AI 主动读取并执行的，它作用于代码生成的源头，而不是事后检查。

如何使用该技能？

技能的核心用法是"用自然语言提需求，AI 按规范产出代码"。以下按典型操作流程展开。

步骤 1：确认技能自动激活的条件

技能会在以下场景自动激活，无需手动调用：

  • 创建或修改路由、端点、API；
  • 构建控制器、服务、仓库；
  • 实现中间件（认证、验证、错误处理）；
  • 使用 Prisma 进行数据库操作；
  • 使用 Sentry 进行错误跟踪；
  • 使用 Zod 进行输入验证；
  • 进行配置管理；
  • 后端测试与重构。

步骤 2：用"业务语言"描述需求，而不是"实现语言"

不推荐的提问方式：

帮我在 router 里写一个注册接口，用 Prisma 插入数据。

这种说法会诱导 AI 把逻辑塞进路由层，与技能原则冲突。

推荐方式：

在用户服务中新增一个注册接口：接收邮箱和密码，校验格式，检查邮箱是否已被占用，然后创建用户并返回用户基本信息。

技能会引导 AI 按"路由 → 控制器 → 服务 → 仓库"的顺序产出完整代码。

步骤 3：读取并核对输出结构

一次合格的输出通常包含以下部分：

  1. Zod 校验模式（放在 validators/）
const registerSchema = z.object({
    email: z.string().email(),
    password: z.string().min(8),
});
  1. 控制器（继承 BaseController，统一成功与错误处理）
export class UserController extends BaseController {
    async register(req: Request, res: Response): Promise<void> {
        try {
            const data = registerSchema.parse(req.body);
            const user = await this.userService.register(data);
            this.handleSuccess(res, user);
        } catch (error) {
            this.handleError(error, res, 'register');
        }
    }
}
  1. 路由（只做委托，不写业务逻辑）
router.post('/register', (req, res) => controller.register(req, res));
  1. 服务层（承载业务判断与依赖注入）
// 服务层负责"邮箱是否已存在"这类业务规则
// 仓库层负责具体的数据库读写
  1. 配置与错误处理：配置从 unifiedConfig 读取，异常经 Sentry 上报。

步骤 4：用检查清单做交付前自检

对照"新后端功能检查清单"逐条确认：路由是否清晰、控制器是否继承 BaseController、服务是否使用依赖注入、复杂查询是否走仓库、输入是否用 Zod 校验、错误是否进 Sentry、是否有单元与集成测试、配置是否来自 unifiedConfig。任何一项没打勾，就直接让 AI 补齐。

步骤 5：遇到细分问题时，主动指定要读的资源文件

当问题进入具体领域时，可以明确指向对应资源文件，例如：

参考 sentry-and-monitoring.md，帮我配置 instrument.ts 并说明它为什么必须最先导入。

步骤 6：新建微服务时使用服务模板与清单

技能推荐以 blog-api（面向 REST API）和 auth-service（面向认证模式）作为成熟模板。新建服务时，先对齐目录结构与中间件栈，再按"新微服务检查清单"逐项落地。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
backend-dev-guidelines（本技能） AI 原生后端架构规范 分层架构、BaseController、Sentry、Zod、unifiedConfig、仓库模式、反模式清单、11 个资源文件 需在支持技能的 AI 环境中安装；具体门槛以官方说明为准 团队统一 Node.js/Express/TypeScript 微服务写法；新人带教；存量重构 优势：规范作用于代码生成源头，自动激活、免重复交代、渐进披露不撑爆上下文。不足：强绑定 Node.js/Express/TypeScript 技术栈，其他语言栈不适用
通用 AI 编程助手 通用代码补全与问答 行内补全、函数生成、自然语言问答 安装编辑器插件即可，门槛低 日常编码加速、陌生 API 查询 优势：上手快、覆盖面广。不足：不携带团队架构约束，生成代码风格随机，容易写出"能跑但不合规"的实现
Lint / 静态检查工具 代码风格与潜在缺陷检测 规则校验、自动修复、CI 卡点 需配置规则文件，接入 CI 提交前检查、流水线卡点 优势：自动化、可强制卡点。不足：只能识别语法与风格层面的问题，判断不了"业务逻辑不该写在路由层"这类架构问题
官方框架文档 / 团队规范 Wiki 知识沉淀 架构说明、最佳实践、示例代码 零安装，但需要主动查阅 学习、疑难排查、新人阅读 优势：信息完整、权威。不足：只读、被动，写代码时不会被自动引用，实际执行率低
自建代码脚手架模板 工程初始化 生成目录结构、样板代码、依赖配置 需要维护模板仓库，跟随框架升级 新建服务、批量铺开标准化 优势：一次性生成规范骨架。不足：只管"起点"不管"过程"，后续迭代中的偏离无法约束

选型建议：静态检查工具解决"格式对不对"，脚手架解决"起点齐不齐"，而本技能解决"过程稳不稳"。三者并非替代关系，配合使用效果最佳。

该技能的典型应用场景与实际体验情况

场景一：新人加入多微服务项目，第一天就要提交代码

角色：刚入职的 Node.js 后端工程师。 痛点：项目里有 blog-api、auth-service、notifications-service 等多个服务，每个服务的写法看似相近又不完全相同；新人不知道该继承谁的控制器、配置从哪读、错误怎么上报。 使用方式：安装技能后，直接描述"我要在认证服务里加一个刷新令牌的接口"，AI 输出的代码天然带 BaseController、Zod 校验和 Sentry 上报，新人只需理解而不用先背熟规范。 实际体验：上手难度低。新人第一次 PR 就能达到团队规范水位，Review 意见从"你这样写不对"变成"这里逻辑可以再优化"。

场景二：存量接口改造，把业务逻辑从路由层剥离

角色：负责重构的老员工。 痛点：历史遗留的 router.post('/submit', ...) 里塞了两百行逻辑，没人敢动；想改造又怕改出事故。 使用方式：把改造目标拆解成分层任务——先抽 Zod 校验、再抽服务层、最后收敛到控制器，逐步让 AI 按 services-and-repositories.md 与 complete-examples.md 的思路重构。 实际体验：效果明显，但需要注意分批改造。一次性让 AI 重写整个文件，容易丢失原有的边界条件处理，建议每完成一层就跑一遍现有测试。

场景三：统一错误处理与可观测性建设

角色：技术负责人 / SRE 协作方。 痛点：各服务错误格式五花八门，线上排查靠 console.log 与人工翻日志，故障定位慢。 使用方式：以 sentry-and-monitoring.md 与 async-and-errors.md 为依据，统一 instrument.ts 的导入顺序、asyncErrorWrapper 的包装方式、自定义错误类型体系。 实际体验：改造后错误统一进入 Sentry，按服务、按接口聚合，排查路径从"翻日志"变成"看事件"。注意 instrument.ts 必须在应用入口最先导入，否则监控数据会缺失，这是最容易漏掉的一点。

场景四：多服务并行开发时的规范一致性保障

角色：跨三个服务同时排期的开发小组。 痛点：三个人三种写法，合并时冲突不断；同一个"用户不存在"的错误，三个服务返回三种结构。 使用方式：把技能作为小组共用的基础配置，所有人在同一套规范下生成代码，PR 时用"新增后端功能检查清单"统一自检。 实际体验：前期需要一次集体对齐（约半天），之后协作摩擦显著下降。需要注意：技能只管 Node.js 技术栈内的规范，跨语言服务的统一仍需另行约定接口契约。

该技能能为用户带来的价值

1. 把"隐性规范"变成"显性执行"

团队规范往往写在 Wiki 里、藏在资深工程师的脑子里。技能把它变成 AI 每次生成代码时都会读取的上下文，执行率从"看心情"变成"默认遵守"。这是最根本的价值——规范不再依赖人的自觉。

2. 显著压缩 Code Review 的无效往返

过去 Reviewer 要反复指出"这里该用 unifiedConfig"“这个接口没做校验”“错误没上报 Sentry”。当这些问题在生成阶段就被规避，Review 的注意力可以集中到业务逻辑与边界条件本身，评审质量与速度同步提升。

3. 大幅降低新人上手门槛

新人不需要先通读十几个服务的源码才能动手。技能内置的目录结构、命名约定、七条核心原则、两份检查清单，本身就是一份可执行的上手手册。

4. 减少线上故障的定位成本

Sentry 统一上报 + 结构化错误处理，让"线上报错了"从"翻日志猜"变成"看事件查"。可观测性不是事后补的，而是在写第一行业务代码时就已经内置。

5. 让重构从"不敢碰"变成"可分步推进"

技能提供了完整的重构指南与反模式清单，把"大重构"拆解为"逐条消除反模式"。团队可以按周推进，风险可控。

6. 长期价值：架构知识可传承

规范沉淀在技能文件里，不会因为某个核心成员离职而丢失。新项目、新服务、新成员都可以复用同一套上下文，团队的后端工程能力形成可积累的资产。

常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

在支持技能机制的 AI 环境中，搜索技能英文名 backend-dev-guidelines 或技能ID 12244 即可定位并安装，安装后确认状态为启用。具体的安装入口、命令与是否收费取决于所在技能平台的政策，请以官方说明为准。安装完成后建议用一个"新增接口"的需求做一次验证，观察输出是否遵循分层架构与 BaseController 模式。

Q2：我的项目不是 Node.js/Express/TypeScript，能用吗？

不建议。该技能的所有内容——分层架构、BaseController、Prisma 仓库模式、Zod 校验、unifiedConfig、Sentry 集成——都围绕 Node.js/Express/TypeScript 微服务构建。其他语言栈（如 Python、Java、Go）即便安装了，AI 也无法从中获得可执行的规范，反而可能产生误导。

Q3：技能会强制改写我现有的代码吗？

不会。技能本身不执行任何自动化改写，它提供的是 AI 生成代码时的上下文与约束。是否改、改多少，完全由你的指令决定。对于存量项目，建议按"先新增后改造"的顺序推进：新接口直接按规范写，存量接口按反模式清单逐条消除，每改一层就回归一次测试。

Q4：它和 ESLint、代码脚手架、官方文档是什么关系？该选哪个？

它们解决的是不同层面的问题，不冲突：

  • ESLint 等静态检查：管"格式与语法层面对不对"，可在 CI 强制卡点；
  • 代码脚手架：管"项目起点齐不齐"，负责初始化目录与依赖；
  • 官方文档 / 团队 Wiki：管"知识全不全"，但需要人主动查阅；
  • 本技能：管"生成过程稳不稳"，在代码被写出来的那一刻就对齐架构。

理想组合是：脚手架铺骨架 → 技能约束日常生成 → Lint 卡最后一道关。

Q5：技能里的 11 个资源文件都要读吗？会不会太重？

不需要。这正是"渐进披露"设计的意义：主文件控制在 500 行以内，只承载最核心的七条原则、目录结构、检查清单与导航表；11 个资源文件按主题拆分，只在遇到具体问题（如"事务怎么写"“中间件顺序怎么排”“测试覆盖率怎么算”）时才深入对应文件。这样既能保证 AI 上下文不被撑爆，又能在需要细节时随时下钻。