AI 技能AI 插件人工智能开发工具【免费下载链接】claude-code-infrastructure-showcaseExamples of my Claude Code infrastructure with skill auto-activation, hooks, and agents项目地址https://gitcode.com/gh_mirrors/cl/claude-code-infrastructure-showcase点击查看免费下载本篇技术指南以 claude-code-infrastructure-showcase 仓库中 backend-dev-guidelines 技能的核心资源文档 architecture-overview.md 为骨架完整讲解 Node.js/Express/TypeScript 微服务项目中四层分层架构Routes → Controllers → Services → Repositories的设计原理、请求生命周期、目录组织与职责边界。读完本文你将掌握可复制的分层架构落地模板、BaseController 错误处理模式、依赖注入与仓储模式、中间件注册顺序等一整套可直接照搬的实战方案并理解邮件服务Email Service成熟模式与表单服务Form Service过渡模式之间的差异取舍。1. 四层架构模式每一层只做一件事backend-dev-guidelines 技能定义的核心是分层架构Layered Architecture它把一次 HTTP 请求从进入到落库的完整链路切分为四个职责单一的层次┌─────────────────────────────────────┐ │ HTTP Request │ └───────────────┬─────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Layer 1: ROUTES │ │ - Route definitions only │ │ - Middleware registration │ │ - Delegate to controllers │ │ - NO business logic │ └───────────────┬─────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Layer 2: CONTROLLERS │ │ - Request/response handling │ │ - Input validation │ │ - Call services │ │ - Format responses │ │ - Error handling │ └───────────────┬─────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Layer 3: SERVICES │ │ - Business logic │ │ - Orchestration │ │ - Call repositories │ │ - No HTTP knowledge │ └───────────────┬─────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Layer 4: REPOSITORIES │ │ - Data access abstraction │ │ - Prisma operations │ │ - Query optimization │ │ - Caching │ └───────────────┬─────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Database (MySQL) │ └─────────────────────────────────────┘关键原则Key Principle每一层只有且仅有一个责任。Routes 只做路由注册Controllers 只做请求/响应处理Services 只承载业务逻辑Repositories 只做数据访问。这个原则在 SKILL.md 中被提炼为「核心原则第 1 条Routes Only Route, Controllers Control」——路由里绝不允许出现 200 行业务逻辑而是必须委托给控制器// ❌ NEVER: Business logic in routes router.post(/submit, async (req, res) { // 200 lines of logic }); // ✅ ALWAYS: Delegate to controller router.post(/submit, (req, res) controller.submit(req, res));为什么选择这种架构架构文档从四个维度论证了分层设计的收益Testability可测试性——每一层都能独立测试依赖可以轻松 mock测试边界清晰。例如 services-and-repositories.md 中的单元测试模板就是用jest.mock(../repositories/UserRepository)隔离数据库只测UserService.createUser的业务规则邮箱冲突抛ConflictError、角色非法抛ValidationError。Maintainability可维护性——变更被隔离在特定层次内业务逻辑与 HTTP 关注点分离Bug 定位成本低。当你在 Controller 里看到PrismaService.main.user.findUnique时几乎可以立刻判定这是架构违规。Reusability可复用性——Services 可以被路由、cron 任务、脚本共同调用Repositories 隐藏了数据库实现细节业务逻辑完全不绑定 HTTP。这意味着同一套UserService既可以服务 REST 端点也可以被批处理任务复用。Scalability可扩展性——新增端点只需遵循既有模式结构一致、模式清晰团队协作成本随规模增长保持稳定。2. 请求生命周期一次 POST 请求的完整旅程完整调用链示例架构文档给出了POST /api/users从进入到返回的八步完整流程1. HTTP POST /api/users ↓ 2. Express matches route in userRoutes.ts ↓ 3. Middleware chain executes: - SSOMiddleware.verifyLoginStatus (authentication) - auditMiddleware (context tracking) ↓ 4. Route handler delegates to controller: router.post(/users, (req, res) userController.create(req, res)) ↓ 5. Controller validates and calls service: - Validate input with Zod - Call userService.create(data) - Handle success/error ↓ 6. Service executes business logic: - Check business rules - Call userRepository.create(data) - Return result ↓ 7. Repository performs database operation: - PrismaService.main.user.create({ data }) - Handle database errors - Return created user ↓ 8. Response flows back: Repository → Service → Controller → Express → Client这条链路中的每一个跳板都有对应的底层佐证第 3 步的 SSO 认证对应 middleware-guide.md 中的SSOMiddlewareClient.verifyLoginStatus——校验req.cookies.refresh_token通过jwt.verify解码后把 claims 写入res.locals失败则返回 401。第 3 步的审计追踪auditMiddleware基于 Node.js 原生AsyncLocalStorage实现把userId、impersonatedBy、requestId等上下文存入auditContextStorage整个请求期间任意 Service/Repository 都能通过getAuditContext()取到无需逐层传递参数。第 5 步的 Zod 校验createUserSchema.parse(req.body)校验失败抛出z.ZodError映射为 400。第 7 步的 Prisma 操作PrismaService.main.user.create({ data })对应 database-patterns.md 中的标准用法且必须先检查PrismaService.isAvailable。中间件执行顺序关键规则中间件严格按照注册顺序执行架构文档给出的标准顺序为app.use(Sentry.Handlers.requestHandler()); // 1. Sentry tracing (FIRST) app.use(express.json()); // 2. Body parsing app.use(express.urlencoded({ extended: true })); // 3. URL encoding app.use(cookieParser()); // 4. Cookie parsing app.use(SSOMiddleware.initialize()); // 5. Auth initialization // ... routes registered here app.use(auditMiddleware); // 6. Audit (if global) app.use(errorBoundary); // 7. Error handler (LAST) app.use(Sentry.Handlers.errorHandler()); // 8. Sentry errors (LAST)铁律错误处理器必须注册在路由之后Error handlers must be registered AFTER routes!。如果错误中间件提前注册它永远无法捕获路由层抛出的错误。middleware-guide.md 还补充了配套的asyncErrorWrapper——把返回 Promise 的异步 handler 包裹为 try/catch 并next(error)确保 Express 4 中异步路由的 rejected promise 不会逃逸export function asyncErrorWrapper( handler: (req: Request, res: Response, next: NextFunction) Promiseany ) { return async (req: Request, res: Response, next: NextFunction) { try { await handler(req, res, next); } catch (error) { next(error); } }; }3. 服务对比成熟模式与过渡模式Email Service成熟模式 ✅—— 新服务的模板架构文档明确把 Email Service 树为标杆新服务应直接以此为模板全面的BaseController内置 Sentry 集成路由层干净委托零业务逻辑一致的依赖注入模式中间件组织良好、全链路类型安全、错误处理出色。其目录结构email/src/ ├── controllers/ │ ├── BaseController.ts ✅ Excellent template │ ├── NotificationController.ts ✅ Extends BaseController │ └── EmailController.ts ✅ Clean patterns ├── routes/ │ ├── notificationRoutes.ts ✅ Clean delegation │ └── emailRoutes.ts ✅ No business logic ├── services/ │ ├── NotificationService.ts ✅ Dependency injection │ └── BatchingService.ts ✅ Clear responsibility └── middleware/ ├── errorBoundary.ts ✅ Comprehensive └── DevImpersonationSSOMiddleware.ts其中的NotificationService是依赖注入的教科书级示范通过构造函数注入prisma、batchingService、emailComposer业务方法createNotification→routeNotification→shouldBatchEmail→getUserPreferences命名清晰、各司其职并内置带 TTL 的偏好缓存CACHE_TTL默认 5 分钟。完整代码见 services-and-repositories.md。Form Service过渡模式 ⚠️—— 学习与规避并存值得学习Learn fromworkflow/目录的事件溯源架构WorkflowEngineV3.ts、创新性的DryRunWrapper.tsmiddleware/auditMiddleware.ts的 AsyncLocalStorage 模式综合权限系统与良好的 Sentry 集成。需要规避AvoidresponseRoutes.ts中 200 行的路由内业务逻辑反面教材的完整剖析见 routing-and-controllers.md 的 Anti-Pattern 章节60 处直接process.env使用违反统一配置原则详见下文第 6 节控制器命名不一致formController.ts小写命名 vsUserProfileController.tsPascalCase 命名仓储模式使用极少——架构文档明确记录「Current Gap: Only 1 repository exists (WorkflowRepository)」这是该过渡服务当前最突出的架构欠账。form/src/ ├── routes/ │ ├── responseRoutes.ts ❌ Business logic in routes │ └── proxyRoutes.ts ✅ Good validation pattern ├── controllers/ │ ├── formController.ts ⚠️ Lowercase naming │ └── UserProfileController.ts ✅ PascalCase naming ├── workflow/ ✅ Excellent architecture! │ ├── core/ │ │ ├── WorkflowEngineV3.ts ✅ Event sourcing │ │ └── DryRunWrapper.ts ✅ Innovative │ │ └── services/ └── middleware/ └── auditMiddleware.ts ✅ AsyncLocalStorage pattern可以推断两套服务并存正是「渐进式重构」的典型状态——新服务按成熟模板落地旧服务逐步向模板迁移这与 SKILL.md 中「New Backend Feature Checklist路由→控制器→服务→仓储→校验→Sentry→测试→配置」的清单化推进策略一脉相承。4. 目录结构原理每个目录的职责与命名规范架构文档逐目录给出了放置原则配合 SKILL.md 的命名规范构成可直接复制的标准骨架目录职责命名规范controllers/解析请求参数、Zod 校验、调用服务、格式化响应、统一错误处理、设置状态码PascalCase Controller如UserController.tsservices/业务规则、多仓储编排、事务管理、业务校验不感知 HTTPcamelCase Service如userService.tsrepositories/Prisma 查询、查询优化、数据库错误处理、缓存层隐藏 Prisma 实现细节PascalCase Repository如UserRepository.tsroutes/仅注册路由、挂中间件、委托控制器严禁业务逻辑camelCase Routes如userRoutes.tsmiddleware/认证、审计、错误边界、校验、自定义横切关注点camelCaseconfig/unifiedConfig.ts类型安全配置单一事实来源—types/特性类型定义、DTO、请求/响应类型、领域模型{feature}.types.ts中间件的三种类型从源码组织方式看middleware 目录按处理时机分为三类见 middleware-guide.md请求处理型handler 之前认证、审计、解析——如SSOMiddlewareClient.verifyLoginStatus响应处理型handler 之后格式化、补充响应信息错误处理型错误边界如errorBoundary根据错误类型映射状态码、上报 Sentry、返回用户友好信息。关于仓储层的现实差距架构文档诚实记录了当前项目中仓储层的覆盖率不足仅WorkflowRepository一个。这意味着新代码应主动补齐仓储模式而 Service 中直接调用PrismaService.main的旧代码属于待迁移项。database-patterns.md 给出了判断标准复杂查询含 join/include、多处复用、需要缓存、需要 mock 测试时才建仓储一次性简单查询与原型阶段可以跳过之后再重构。5. 模块组织特性化 vs 扁平化特性化组织Feature-Based当某个特性文件数达到5 个以上、存在清晰子领域、逻辑分组能提升可读性时使用子目录src/workflow/ ├── core/ # Core engine ├── services/ # Workflow-specific services ├── actions/ # System actions ├── models/ # Domain models ├── validators/ # Workflow validation └── utils/ # Workflow utilitiesForm Service 的workflow/目录就是这种组织方式的实战代表——把事件溯源引擎、DryRun 包装器、工作流服务、动作、模型、校验器、工具类分层归置架构文档评价其为「Excellent architecture!」。扁平化组织Flat简单特性少于 5 个文件、无明确子领域直接平铺清晰优先src/ ├── controllers/UserController.ts ├── services/userService.ts ├── routes/userRoutes.ts └── repositories/UserRepository.ts经验法则先扁平起步当文件数跨过 5 个阈值、开始出现「不知道该放哪个目录」的模糊归属时再升级为特性化子目录——这与渐进式重构的整体策略一致。6. 职责分离Separation of Concerns什么代码该放哪层各层「该做什么 / 不该做什么」速查表层✅ 该做❌ 不该做Routes路由定义、中间件注册、控制器委托业务逻辑、数据库操作、校验逻辑应在校验器或控制器Controllers请求解析params/body/query、Zod 输入校验、服务调用、响应格式化、错误处理业务逻辑、数据库操作Services业务逻辑、业务规则强制、多仓储编排、事务管理HTTP 关注点Request/Response、直接 Prisma 调用必须走仓储RepositoriesPrisma 操作、查询构造、数据库错误处理、缓存业务逻辑、HTTP 关注点架构文档强调Repositories 层必须隐藏 Prisma 实现细节——这意味着 Service 层与 Prisma Client 之间永远隔着一层仓储未来替换 ORM、加缓存、加读写分离都只影响仓储内部。这与 SKILL.md 的核心原则「6. Use Repository Pattern for Data Access」互相印证。完整示例用户创建User Creation以POST /users为例四层各司其职的完整代码Route —— 只做注册与委托router.post(/users, SSOMiddleware.verifyLoginStatus, auditMiddleware, (req, res) userController.create(req, res) );Controller —— 校验 调用服务 统一响应async create(req: Request, res: Response): Promisevoid { try { const validated createUserSchema.parse(req.body); const user await this.userService.create(validated); this.handleSuccess(res, user, User created); } catch (error) { this.handleError(error, res, create); } }Service —— 执行业务规则async create(data: CreateUserDTO): PromiseUser { // Business rule: check if email already exists const existing await this.userRepository.findByEmail(data.email); if (existing) throw new ConflictError(Email already exists); // Create user return await this.userRepository.create(data); }Repository —— 执行数据库操作async create(data: CreateUserDTO): PromiseUser { return PrismaService.main.user.create({ data }); } async findByEmail(email: string): PromiseUser | null { return PrismaService.main.user.findUnique({ where: { email } }); }Notice:Each layer has clear, distinct responsibilities!每一层都有清晰、独立的职责——业务规则邮箱唯一性在 Service 中数据访问findUnique/create在 Repository 中HTTP 语义res只在 Controller 中这四段代码互不越界。7. 与技能的配套落地7 条核心原则与后续学习路径architecture-overview.md 是 backend-dev-guidelines 技能的 11 个资源文件之一负责「架构、请求生命周期、职责分离」三大主题其余细节由技能主页与各资源文件分别承接链接已转换为仓库根目录相对路径SKILL.md主指南—— 7 条核心原则① 路由只路由、控制器只控制② 所有控制器继承 BaseController③ 所有错误上报 Sentry④ 使用 unifiedConfig绝不直接process.env⑤ 所有输入用 Zod 校验⑥ 数据访问走仓储模式⑦ 全面测试。并附「新后端特性清单」与「新微服务清单」两张可直接打勾的落地清单。routing-and-controllers.md—— BaseController 完整实现handleError/handleSuccess/withTransaction/validateRequest/Sentry breadcrumb 与 metric 封装、HTTP 状态码速查表、以及「200 行路由逻辑 → 8 行干净路由」的分步重构指南。services-and-repositories.md—— 依赖注入模式NotificationService、单例模式PermissionService、仓储模板、服务设计五原则单一职责、方法命名、显式返回类型、有意义的错误、避免 God Service、缓存与失效策略、服务单元测试模板。middleware-guide.md—— SSO 认证中间件、AsyncLocalStorage 审计中间件、错误边界中间件、可组合中间件withAuthAndAudit与中间件关键顺序。database-patterns.md—— PrismaService 用法、交互式事务maxWait/timeout、查询优化select限定字段、谨慎include、N1 查询防治、Prisma 错误码映射P2002 冲突 / P2003 外键 / P2025 记录不存在。configuration.md—— unifiedConfig 三层优先级config.ini 环境变量 默认值、启动期校验、密钥管理config.ini/.env 不入库与grep -r process.env src/迁移排查法。complete-examples.md—— 完整的UserController含 Zod 校验、withTransaction性能追踪、204 删除语义、服务、路由、仓储及端到端特性示例。提示.agents/skills/是.claude/skills/的标准镜像目录遵循跨 Agent 的 Agent Skills 规范供 Codex 等工具原生读取仓库通过.claude/scripts/sync-agent-skills.sh保持二者同步verify-setup会检测漂移。本文所有资源链接均指向.agents/镜像下的同一份内容。8. 实战建议如何基于本架构开启新服务综合架构文档、SKILL.md 与各资源文件新建一个微服务时按以下顺序落地搭骨架按第 4 节目录结构创建config/、controllers/、services/、repositories/、routes/、middleware/、types/、validators/、tests/加instrument.tsSentry必须作为首个导入与app.ts/server.ts建基座实现unifiedConfig.ts类型安全配置与BaseControllerSentry 集成 统一成功/失败响应 withTransaction性能追踪参考 configuration.md 与 routing-and-controllers.md铺中间件链按第 2 节顺序注册 Sentry → body 解析 → cookie → SSO → 路由 → 错误边界 → Sentry 错误处理器按四层写特性路由只委托、控制器只处理请求、服务只写业务规则依赖注入 显式返回类型 有意义错误、仓储只做 Prismaselect 限字段、include 克制、事务兜底每个特性对照「用户创建」四段示例逐行对齐补齐测试与监控Service 层单元测试mock 仓储、错误全量进 Sentry、中间件用asyncErrorWrapper兜底异步异常对照成熟模板自查以 Email Service 目录结构为基准逐项核对是否出现「路由内业务逻辑」「直接 process.env」「直接 Prisma」「God Service」等反模式。这套分层架构的价值在于它把「可测试、可维护、可复用、可扩展」从口号变成了目录结构和代码模板中的硬约束——新成员照着目录放代码、沿着调用链写逻辑架构一致性就不再依赖个人自觉。仓库中的 Email/Form 双服务对比更说明架构演进是渐进的过程允许旧服务带病过渡但新代码必须站在成熟模式这一侧。相关文件导航仓库根目录相对路径本文核心 architecture-overview.md技能主指南 SKILL.md路由与控制器 routing-and-controllers.md服务与仓储 services-and-repositories.md中间件指南 middleware-guide.md数据库模式 database-patterns.md配置管理 configuration.md完整示例 complete-examples.md仓库总览与集成方式 README.md赞分享AI 技能AI 插件人工智能开发工具【免费下载链接】claude-code-infrastructure-showcaseExamples of my Claude Code infrastructure with skill auto-activation, hooks, and agents项目地址https://gitcode.com/gh_mirrors/cl/claude-code-infrastructure-showcase点击查看免费下载相关推荐claude-code-infrastructure-showcase 后端分层架构实战指南Routes→Controllers→Services→Repositories 模式全解析claude code infrastructure showcase 后端分层架构实战指南Routes→Controllers→Services→ReposAI 技能AI 插件人工智能开发工具claude-code-infrastructure-showcase 后端分层指南Services 与 Repositories 业务逻辑与数据访问完整实践claude code infrastructure showcase 后端分层指南Services 与 Repositories 业务逻辑与数据访问完整实践AI 技能AI 插件人工智能开发工具Claude Code 后端开发指南Services 与 Repositories 业务逻辑层分层实践Claude Code 后端开发指南Services 与 Repositories 业务逻辑层分层实践 导读 本文是仓库内 backend dev guideAI 技能AI 插件人工智能开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考