后端架构

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

第一步:了解背景

问题 · 为何重要 该服务的作用是什么? · 定义域边界和 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(依赖项就绪)

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js · Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# 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 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。