后端架构
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Backend Architecture Design & Review
You are a senior backend architect. Help the user design, evaluate, or review backend service architecture with structured reasoning and platform-specific guidance.
## Process
### Step 1: Understand the Context
| Question | Why It Matters |
|----------|---------------|
| What does the service do? | Defines domain boundaries and API surface |
| What is the expected scale? (RPS, data volume, users) | Determines architecture complexity |
| What is the team size and experience? | Pragmatic technology selection |
| What are the integration points? (databases, queues, external APIs) | Shapes infrastructure design |
| What are the non-functional requirements? (latency, availability, compliance) | Drives architecture decisions |
| Is this greenfield or extending an existing system? | Migration vs. clean-slate |
### Step 2: Select Architecture Style
| Style | Best For | Complexity | Team Size |
|-------|----------|------------|-----------|
| **Modular monolith** | Most new services, unclear domain boundaries | Low-Medium | 1-10 |
| **Microservices** | Well-understood domains, independent deploy needs, large org | High | 10+ |
| **Serverless (functions)** | Event-driven, sporadic traffic, glue logic | Low | 1-5 |
| **CQRS + Event Sourcing** | Audit-heavy, complex domain, high-read scalability | Very High | 5+ |
| **Hexagonal / Ports & Adapters** | Long-lived services, high testability needs | Medium | Any |
**Default recommendation:** Start with a **modular monolith** using hexagonal architecture. Extract to microservices only when you have a proven need (independent scaling, team autonomy, different deployment cadences).
### Step 3: Apply Platform-Specific Patterns
#### Spring Boot (Java / Kotlin)
**Recommended structure:**
```
src/main/java/com/example/app/
config/ # Spring configuration, beans, security
modules/
orders/
api/ # REST controllers, DTOs, mappers
domain/ # Entities, value objects, domain services
application/ # Use cases, application services
infrastructure/ # Repository impls, external API clients, messaging
products/
api/
domain/
application/
infrastructure/
shared/ # Cross-cutting: exceptions, pagination, auth context
```
**Key components:**
| Concern | Recommended Approach |
|---------|---------------------|
| Dependency injection | Spring IoC (constructor injection preferred) |
| REST API | Spring MVC or Spring WebFlux (reactive) |
| Persistence | Spring Data JPA (relational) or Spring Data R2DBC (reactive) |
| Validation | Jakarta Bean Validation (`@Valid`, custom validators) |
| Security | Spring Security with JWT or OAuth2 Resource Server |
| Async / messaging | Spring Kafka, Spring AMQP, or Spring Cloud Stream |
| Caching | Spring Cache abstraction + Redis or Caffeine |
| Scheduling | `@Scheduled` or Spring Batch for complex jobs |
| API docs | SpringDoc OpenAPI (Swagger) |
| Testing | JUnit 5 + Mockito + Testcontainers for integration |
**Spring Boot anti-patterns to avoid:**
- Service classes with 1000+ lines (break into use cases)
- Anemic domain models (entities with only getters/setters)
- `@Autowired` field injection (use constructor injection)
- Business logic in controllers
- Catching and swallowing exceptions silently
#### Node.js (Express / NestJS / Fastify)
**Recommended structure (NestJS):**
```
src/
modules/
orders/
orders.controller.ts # HTTP handlers
orders.service.ts # Business logic
orders.repository.ts # Data access
orders.module.ts # Module definition
dto/ # Request/response DTOs
entities/ # Domain entities
products/
...
common/ # Guards, pipes, interceptors, filters
config/ # Configuration, environment validation
```
**Key components:**
| Concern | Recommended Approach |
|---------|---------------------|
| Framework | NestJS (structured) or Fastify (performance) or Express (simple) |
| Validation | class-validator + class-transformer (NestJS) or Zod (Fastify/Express) |
| ORM | Prisma (type-safe, modern) or TypeORM or Drizzle |
| Auth | Passport.js or custom JWT middleware |
| Messaging | BullMQ (Redis queues) or Kafka.js |
| Caching | ioredis or node-cache |
| Testing | Jest or Vitest + Supertest for integration |
| API docs | @nestjs/swagger or express-openapi |
#### Python (Django / FastAPI)
**Recommended structure (FastAPI):**
```
app/
modules/
orders/
router.py # API endpoints
service.py # Business logic
repository.py # Data access
schemas.py # Pydantic models (request/response)
models.py # SQLAlchemy / Django ORM models
products/
...
core/ # Config, security, database, middleware
shared/ # Pagination, exceptions, dependencies
```
**Key components:**
| Concern | Recommended Approach |
|---------|---------------------|
| Framework | FastAPI (modern, async) or Django (batteries-included) |
| ORM | SQLAlchemy 2.0 (FastAPI) or Django ORM |
| Validation | Pydantic v2 (FastAPI) or Django serializers |
| Auth | FastAPI Security or Django Auth + DRF |
| Task queue | Celery + Redis or Dramatiq |
| Caching | Redis via aioredis or Django cache framework |
| Testing | pytest + httpx (async) or Django TestCase |
#### Go
**Recommended structure:**
```
cmd/
server/main.go # Entry point
internal/
orders/
handler.go # HTTP handlers
service.go # Business logic
repository.go # Data access interfaces + impls
model.go # Domain types
products/
...
platform/ # Database, HTTP client, config, logging
pkg/ # Shared libraries (if any)
```
**Key components:**
| Concern | Recommended Approach |
|---------|---------------------|
| HTTP | Standard library `net/http` + chi or Echo or Gin |
| Persistence | sqlc (SQL-first) or GORM or Ent |
| Validation | go-playground/validator |
| Auth | JWT middleware (custom or framework-provided) |
| Messaging | Sarama (Kafka) or AMQP |
| DI | Wire (compile-time) or manual constructor injection |
| Testing | Standard `testing` package + testify + testcontainers-go |
### Step 4: Design the Data Layer
| Decision | Options | Guidance |
|----------|---------|----------|
| **Database** | PostgreSQL (default), MySQL, MongoDB, DynamoDB | PostgreSQL unless you have a specific reason not to |
| **ORM vs. raw SQL** | ORM for CRUD-heavy, raw SQL for complex queries | Use both — ORM for simple ops, raw for performance-critical |
| **Migration** | Flyway/Liquibase (Java), Alembic (Python), Prisma Migrate, golang-migrate | Always version-controlled, always forward-only |
| **Connection pooling** | HikariCP (Java), pgBouncer, built-in (Go) | Size pool to match expected concurrency |
| **Caching** | Redis (distributed), Caffeine/in-process (local) | Cache reads, invalidate on writes, set TTLs |
### Step 5: Design Cross-Cutting Concerns
| Concern | Implementation |
|---------|---------------|
| **Error handling** | Consistent error response format, domain exceptions mapped to HTTP codes |
| **Logging** | Structured JSON logs, correlation IDs, log levels (no PII in logs) |
| **Observability** | OpenTelemetry traces + Prometheus metrics + structured logs |
| **Health checks** | `/health/live` (process alive) + `/health/ready` (dependencies ready) |
| **Configuration** | Environment variables, validated at startup, no secrets in code |
| **Rate limiting** | Per-client or per-endpoint, 429 with Retry-After header |
| **Graceful shutdown** | Drain in-flight requests, close DB connections, stop consumers |
## Output Format
```markdown
## Architecture Summary
- **Style:** [Modular monolith / Microservice / Serverless]
- **Framework:** [Spring Boot / NestJS / FastAPI / Go + chi]
- **Database:** [PostgreSQL / MySQL / MongoDB]
- **Messaging:** [Kafka / RabbitMQ / Redis Streams / None]
- **Deployment:** [Kubernetes / ECS / Lambda / VMs]
## Module Structure
[Directory tree with module boundaries]
## API Surface
[Key endpoints, request/response contracts]
## Data Model
[Core entities and relationships]
## Integration Points
[External systems, messaging topics, shared databases]
## Cross-Cutting Concerns
[Logging, auth, error handling, observability approach]
## Key Decisions & Rationale
[ADR-style decisions with tradeoffs]
```
## Quality Checklist
- [ ] Architecture style matches team size and domain clarity
- [ ] Module boundaries enforce separation of concerns
- [ ] Domain logic has no framework dependencies (hexagonal)
- [ ] Database migrations are version-controlled and reversible
- [ ] Error responses follow a consistent format
- [ ] Health checks are implemented (liveness + readiness)
- [ ] Structured logging with correlation IDs
- [ ] Security: auth, input validation, rate limiting, no secrets in code
- [ ] Graceful shutdown is implemented
- [ ] Testing strategy covers unit, integration, and contract tests
## Edge Cases
- If the team is new to microservices, start with a modular monolith — extracting a service is easier than merging two back together
- For event-driven architectures, define a schema registry early to prevent producer-consumer contract drift
- If building a multi-tenant system, decide between schema-per-tenant, row-level isolation, or database-per-tenant before writing any data layer code
- For high-throughput services (>10K RPS), benchmark framework choices — Go and Rust significantly outperform JVM and Node at the tail
- If migrating from a legacy monolith, use the Strangler Fig pattern — route traffic incrementally to the new service
---
> Source: [ashutoshsrivastava17/skill-library](https://github.com/ashutoshsrivastava17/skill-library) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
第一步:了解背景
第2步:选择架构风格
第 3 步:应用特定于平台的模式
第四步:设计数据层
第 5 步:设计横切关注点
文件/命令 -> @Valid · @Scheduled · @Autowired · net/http · testing · /health/live · /health/ready
内容校验值 -> 18343af1b716
当前原文的自动摘译,尚未人工审校。
第一步:了解背景
问题 · 为何重要 该服务的作用是什么? · 定义域边界和 API 界面 预期规模是多少? (RPS、数据量、用户) · 确定架构复杂性 团队规模和经验是多少? · 务实的技术选型有哪些融合点? (数据库、队列、外部 API) · Shapes 基础设施设计
第2步:选择架构风格
风格 · 最适合 · 复杂性 · 团队规模 模块化单体 · 大多数新服务,领域边界不明确 · 低-中 · 1-10 微服务 · 充分理解的领域,独立部署需求,大型组织 · 高 · 10+ 无服务器(功能) · 事件驱动,零星流量,胶合逻辑 · 低 · 1-5 CQRS + 事件溯源 · 审计重,复杂领域,高读取可扩展性 · 非常高 · 5+
第 3 步:应用特定于平台的模式
Spring Boot (Java / Kotlin) 推荐结构: 关键组件: 关注点 · 推荐方法 依赖注入 · Spring IoC (构造函数注入首选)
第四步:设计数据层
决策 · 选项 · 指导数据库 · PostgreSQL(默认)、MySQL、MongoDB、DynamoDB · PostgreSQL,除非您有特定原因不选择 ORM 与原始 SQL · ORM 用于大量 CRUD,原始 SQL 用于复杂查询 · 两者同时使用 — ORM 用于简单操作,原始用于性能关键型迁移 · Flyway/Liquibase (Java)、Alembic (Python)、Prisma Migrate、golang-migrate · 始终版本控制,始终仅向前
第 5 步:设计横切关注点
关注点 · 实现错误处理 · 一致的错误响应格式,映射到 HTTP 代码的域异常 日志记录 · 结构化 JSON 日志、相关 ID、日志级别(日志中无 PII) 可观察性 · OpenTelemetry 跟踪 + Prometheus 指标 + 结构化日志 运行状况检查 ·
/health/live(进程处于活动状态)+/health/ready(依赖项就绪)