[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-bcd45d52-6ab9-4b7f-81f3-6e618bf4ff1b":3,"$fbspPfRjeKUkurtmj1cJ92ju5Gi7DJjkjne7VXjnCki4":42},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":33},"bcd45d52-6ab9-4b7f-81f3-6e618bf4ff1b","backend-dev-guidelines","您是一位在严格架构和可靠性约束下运营生产级服务的资深后端工程师。适用于路由、控制器、服务、存储库、Express 中间件或 Prisma 数据库访问。","cat_coding_backend","mod_coding","sickn33,coding","---\nname: backend-dev-guidelines\ndescription: \"You are a senior backend engineer operating production-grade services under strict architectural and reliability constraints. Use when routes, controllers, services, repositories, express middleware, or prisma database access.\"\nrisk: unknown\nsource: community\ndate_added: \"2026-02-27\"\n---\n\n# Backend Development Guidelines\n\n**(Node.js · Express · TypeScript · Microservices)**\n\nYou are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.\n\nYour goal is to build **predictable, observable, and maintainable backend systems** using:\n\n* Layered architecture\n* Explicit error boundaries\n* Strong typing and validation\n* Centralized configuration\n* First-class observability\n\nThis skill defines **how backend code must be written**, not merely suggestions.\n\n---\n\n## 1. Backend Feasibility & Risk Index (BFRI)\n\nBefore implementing or modifying a backend feature, assess feasibility.\n\n### BFRI Dimensions (1–5)\n\n| Dimension                     | Question                                                         |\n| ----------------------------- | ---------------------------------------------------------------- |\n| **Architectural Fit**         | Does this follow routes → controllers → services → repositories? |\n| **Business Logic Complexity** | How complex is the domain logic?                                 |\n| **Data Risk**                 | Does this affect critical data paths or transactions?            |\n| **Operational Risk**          | Does this impact auth, billing, messaging, or infra?             |\n| **Testability**               | Can this be reliably unit + integration tested?                  |\n\n### Score Formula\n\n```\nBFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)\n```\n\n**Range:** `-10 → +10`\n\n### Interpretation\n\n| BFRI     | Meaning   | Action                 |\n| -------- | --------- | ---------------------- |\n| **6–10** | Safe      | Proceed                |\n| **3–5**  | Moderate  | Add tests + monitoring |\n| **0–2**  | Risky     | Refactor or isolate    |\n| **\u003C 0**  | Dangerous | Redesign before coding |\n\n---\n\n## When to Use\nAutomatically applies when working on:\n\n* Routes, controllers, services, repositories\n* Express middleware\n* Prisma database access\n* Zod validation\n* Sentry error tracking\n* Configuration management\n* Backend refactors or migrations\n\n---\n\n## 2. Core Architecture Doctrine (Non-Negotiable)\n\n### 1. Layered Architecture Is Mandatory\n\n```\nRoutes → Controllers → Services → Repositories → Database\n```\n\n* No layer skipping\n* No cross-layer leakage\n* Each layer has **one responsibility**\n\n---\n\n### 2. Routes Only Route\n\n```ts\n\u002F\u002F ❌ NEVER\nrouter.post('\u002Fcreate', async (req, res) => {\n  await prisma.user.create(...);\n});\n\n\u002F\u002F ✅ ALWAYS\nrouter.post('\u002Fcreate', (req, res) =>\n  userController.create(req, res)\n);\n```\n\nRoutes must contain **zero business logic**.\n\n---\n\n### 3. Controllers Coordinate, Services Decide\n\n* Controllers:\n\n  * Parse request\n  * Call services\n  * Handle response formatting\n  * Handle errors via BaseController\n\n* Services:\n\n  * Contain business rules\n  * Are framework-agnostic\n  * Use DI\n  * Are unit-testable\n\n---\n\n### 4. All Controllers Extend `BaseController`\n\n```ts\nexport class UserController extends BaseController {\n  async getUser(req: Request, res: Response): Promise\u003Cvoid> {\n    try {\n      const user = await this.userService.getById(req.params.id);\n      this.handleSuccess(res, user);\n    } catch (error) {\n      this.handleError(error, res, 'getUser');\n    }\n  }\n}\n```\n\nNo raw `res.json` calls outside BaseController helpers.\n\n---\n\n### 5. All Errors Go to Sentry\n\n```ts\ncatch (error) {\n  Sentry.captureException(error);\n  throw error;\n}\n```\n\n❌ `console.log`\n❌ silent failures\n❌ swallowed errors\n\n---\n\n### 6. unifiedConfig Is the Only Config Source\n\n```ts\n\u002F\u002F ❌ NEVER\nprocess.env.JWT_SECRET;\n\n\u002F\u002F ✅ ALWAYS\nimport { config } from '@\u002Fconfig\u002FunifiedConfig';\nconfig.auth.jwtSecret;\n```\n\n---\n\n### 7. Validate All External Input with Zod\n\n* Request bodies\n* Query params\n* Route params\n* Webhook payloads\n\n```ts\nconst schema = z.object({\n  email: z.string().email(),\n});\n\nconst input = schema.parse(req.body);\n```\n\nNo validation = bug.\n\n---\n\n## 3. Directory Structure (Canonical)\n\n```\nsrc\u002F\n├── config\u002F              # unifiedConfig\n├── controllers\u002F         # BaseController + controllers\n├── services\u002F            # Business logic\n├── repositories\u002F        # Prisma access\n├── routes\u002F              # Express routes\n├── middleware\u002F          # Auth, validation, errors\n├── validators\u002F          # Zod schemas\n├── types\u002F               # Shared types\n├── utils\u002F               # Helpers\n├── tests\u002F               # Unit + integration tests\n├── instrument.ts        # Sentry (FIRST IMPORT)\n├── app.ts               # Express app\n└── server.ts            # HTTP server\n```\n\n---\n\n## 4. Naming Conventions (Strict)\n\n| Layer      | Convention                |\n| ---------- | ------------------------- |\n| Controller | `PascalCaseController.ts` |\n| Service    | `camelCaseService.ts`     |\n| Repository | `PascalCaseRepository.ts` |\n| Routes     | `camelCaseRoutes.ts`      |\n| Validators | `camelCase.schema.ts`     |\n\n---\n\n## 5. Dependency Injection Rules\n\n* Services receive dependencies via constructor\n* No importing repositories directly inside controllers\n* Enables mocking and testing\n\n```ts\nexport class UserService {\n  constructor(\n    private readonly userRepository: UserRepository\n  ) {}\n}\n```\n\n---\n\n## 6. Prisma & Repository Rules\n\n* Prisma client **never used directly in controllers**\n* Repositories:\n\n  * Encapsulate queries\n  * Handle transactions\n  * Expose intent-based methods\n\n```ts\nawait userRepository.findActiveUsers();\n```\n\n---\n\n## 7. Async & Error Handling\n\n### asyncErrorWrapper Required\n\nAll async route handlers must be wrapped.\n\n```ts\nrouter.get(\n  '\u002Fusers',\n  asyncErrorWrapper((req, res) =>\n    controller.list(req, res)\n  )\n);\n```\n\nNo unhandled promise rejections.\n\n---\n\n## 8. Observability & Monitoring\n\n### Required\n\n* Sentry error tracking\n* Sentry performance tracing\n* Structured logs (where applicable)\n\nEvery critical path must be observable.\n\n---\n\n## 9. Testing Discipline\n\n### Required Tests\n\n* **Unit tests** for services\n* **Integration tests** for routes\n* **Repository tests** for complex queries\n\n```ts\ndescribe('UserService', () => {\n  it('creates a user', async () => {\n    expect(user).toBeDefined();\n  });\n});\n```\n\nNo tests → no merge.\n\n---\n\n## 10. Anti-Patterns (Immediate Rejection)\n\n❌ Business logic in routes\n❌ Skipping service layer\n❌ Direct Prisma in controllers\n❌ Missing validation\n❌ process.env usage\n❌ console.log instead of Sentry\n❌ Untested business logic\n\n---\n\n## 11. Integration With Other Skills\n\n* **frontend-dev-guidelines** → API contract alignment\n* **error-tracking** → Sentry standards\n* **database-verification** → Schema correctness\n* **analytics-tracking** → Event pipelines\n* **skill-developer** → Skill governance\n\n---\n\n## 12. Operator Validation Checklist\n\nBefore finalizing backend work:\n\n* [ ] BFRI ≥ 3\n* [ ] Layered architecture respected\n* [ ] Input validated\n* [ ] Errors captured in Sentry\n* [ ] unifiedConfig used\n* [ ] Tests written\n* [ ] No anti-patterns present\n\n---\n\n## 13. Skill Status\n\n**Status:** Stable · Enforceable · Production-grade\n**Intended Use:** Long-lived Node.js microservices with real traffic and real risk\n---\n\n### When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,228,642,"2026-05-16 13:08:04",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":25,"skillCount":32,"createdAt":26},"后端开发","backend","mdi-server","API、数据库、服务端架构",296,[34],{"id":35,"skillId":4,"version":36,"fileName":37,"fileSize":38,"filePath":39,"fileHash":40,"manifest":41,"createdAt":19},"13ccd33e-acab-49a9-855d-8c4386e1cfc4","1.0.0","backend-dev-guidelines.zip",39777,"uploads\u002Fskills\u002Fbcd45d52-6ab9-4b7f-81f3-6e618bf4ff1b\u002Fbackend-dev-guidelines.zip","54f6fdd91c0d066710e07250c3a14559861e13bcc101cbecdc87605e6ef0ff1c","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":8007},{\"path\":\"resources\u002Farchitecture-overview.md\",\"isDirectory\":false,\"size\":12854},{\"path\":\"resources\u002Fasync-and-errors.md\",\"isDirectory\":false,\"size\":6850},{\"path\":\"resources\u002Fcomplete-examples.md\",\"isDirectory\":false,\"size\":16466},{\"path\":\"resources\u002Fconfiguration.md\",\"isDirectory\":false,\"size\":5804},{\"path\":\"resources\u002Fdatabase-patterns.md\",\"isDirectory\":false,\"size\":4925},{\"path\":\"resources\u002Fmiddleware-guide.md\",\"isDirectory\":false,\"size\":5157},{\"path\":\"resources\u002Frouting-and-controllers.md\",\"isDirectory\":false,\"size\":19918},{\"path\":\"resources\u002Fsentry-and-monitoring.md\",\"isDirectory\":false,\"size\":7741},{\"path\":\"resources\u002Fservices-and-repositories.md\",\"isDirectory\":false,\"size\":22287},{\"path\":\"resources\u002Ftesting-guide.md\",\"isDirectory\":false,\"size\":5408},{\"path\":\"resources\u002Fvalidation-patterns.md\",\"isDirectory\":false,\"size\":18026}]",{"code":43,"message":44,"data":45},200,"success",{"items":46,"stats":47,"page":50},[],{"averageRating":48,"totalRatings":48,"ratingCounts":49},0,[48,48,48,48,48],{"limit":51,"offset":48,"hasMore":52,"nextOffset":51,"ratedOnly":16},15,false]