moai-domain-backend

后端开发专家

快速参考

后端开发精通指南——全面介绍后端开发模式，涵盖 API 设计、数据库集成、微服务和现代架构模式。

核心能力：

• API 设计：使用 OpenAPI 3.1 设计 REST、GraphQL、gRPC API
• 数据库集成：PostgreSQL、MongoDB、Redis、缓存策略
• 微服务：服务网格、分布式模式、事件驱动架构
• 安全：身份验证、授权、符合 OWASP 标准
• 性能：缓存、优化、监控、扩展

适用场景：

• 后端 API 开发与架构设计
• 数据库设计与优化
• 微服务实现
• 性能优化与扩展
• 后端系统安全集成

---

实现指南

API 设计模式

RESTful API 架构：

创建一个带有身份验证和响应模型的 FastAPI 应用。定义一个包含 id、email 和 name 字段的 Pydantic UserResponse 模型。使用 HTTPBearer 安全依赖项实现 list_users 和 create_user 端点。列表端点返回 UserResponse 对象列表，而创建端点接受一个 UserCreate 模型并返回单个 UserResponse。

GraphQL 实现：

使用 Strawberry 定义 GraphQL 类型。创建一个包含 id、email 和 name 字段的 User 类型。定义一个 Query 类型，其中包含异步返回 User 对象列表的 users 解析器。将 Query 类型传递给 strawberry.Schema 以生成架构。

数据库集成模式

使用 SQLAlchemy 连接 PostgreSQL：

使用 declarative_base 定义 SQLAlchemy 模型。创建一个 User 模型，其中 id 为主键，email 为唯一字符串，name 为字符串列。配置引擎的连接池参数，包括 pool_size 为 20、max_overflow 为 30，并启用 pool_pre_ping 进行连接健康检查。

使用 Motor 连接 MongoDB：

创建一个以 AsyncIOMotorClient 初始化的 UserService 类。在构造函数中设置数据库和 users 集合。为 email（唯一）和 created_at 字段创建索引。实现 create_user 方法，插入文档并将 inserted_id 作为字符串返回。

微服务架构

使用 Consul 进行服务发现：

创建一个连接到 Consul 的 ServiceRegistry 类。实现 register_service 方法，用名称、ID、端口和健康检查端点注册服务。实现 discover_service 方法，查询健康服务并返回 address:port 字符串列表。

事件驱动架构：

使用 aio_pika 创建一个用于 AMQP 消息传递的 EventBus 类。实现 connect 方法以建立连接和通道。实现 publish_event 方法，将事件类型和数据序列化为 JSON，并将其发布到默认交换机，routing_key 与事件类型相同。

---

高级模式

缓存策略

Redis 集成：

创建一个连接 Redis 的 CacheManager 类。实现一个接受 ttl 参数的 cache_result 装饰器。该装饰器根据函数名称和参数生成缓存键，在 Redis 中检查缓存结果；若缓存未命中，则执行函数并存储结果，同时设置过期时间。使用 json.loads 和 json.dumps 进行序列化。

安全实现

JWT 身份验证：

创建一个使用 CryptContext 进行 bcrypt 密码哈希的 SecurityManager 类。使用该上下文实现 hash_password 和 verify_password 方法。实现 create_access_token 方法，使用 HS256 算法编码带有过期时间的 JWT。若未指定，默认过期时间为 15 分钟。

性能优化

数据库连接池：

创建一个经过优化的 SQLAlchemy 引擎，使用 QueuePool，设置 pool_size 为 20、max_overflow 为 30、启用 pool_pre_ping，并将 pool_recycle 设为 3600 秒。添加 before_cursor_execute 和 after_cursor_execute 事件监听器，以跟踪查询耗时。对超过 100 毫秒阈值的查询记录警告。

---

适配良好

• moai-domain-frontend - 全栈开发集成
• moai-domain-database - 高级数据库模式
• moai-foundation-core - 后端服务的 MCP 服务开发模式
• moai-foundation-quality + moai-ref-owasp-checklist - 安全验证与合规
• moai-foundation-core - 核心架构原则

---

技术栈

主要技术：

• 语言：Python 3.13+、Node.js 20+、Go 1.23
• 框架：FastAPI、Django、Express.js、Gin
• 数据库：PostgreSQL 16+、MongoDB 7+、Redis 7+
• 消息队列：RabbitMQ、Apache Kafka、Redis Pub/Sub
• 容器化：Docker、Kubernetes
• 监控：Prometheus、Grafana、OpenTelemetry

集成模式：

• 使用 OpenAPI 3.1 的 RESTful API
• 使用 Apollo Federation 的 GraphQL
• 用于高性能服务的 gRPC
• 使用 CQRS 的事件驱动架构
• API 网关模式
• 熔断器与弹性模式

---

状态：可用于生产环境 维护者：MoAI-ADK 后端团队

常见的自我开脱

自我开脱	事实
“输入验证可以在前端进行”	前端验证用于改善用户体验，后端验证用于保障安全。两者用途不同，缺一不可。
“这个端点是内部的，不需要身份验证”	已遭入侵的服务可以访问内部端点。零信任意味着每个端点都必须验证身份。
“我之后再添加错误处理”	未处理的错误会泄露堆栈跟踪、连接字符串和内部状态。错误处理是从第一天起就要做的工作。
“ORM 会处理 SQL 注入”	ORM 能保护参数化查询。原始查询、动态筛选条件和 ORDER BY 子句仍需转义。
“这个 API 向后兼容，不需要升级版本”	删除可选字段、更改默认值或修改错误格式，都会破坏现有调用方的兼容性。
“微服务太复杂了，我只要再加一个端点就行”	端点无节制地增长会造出一个伪装成微服务的单体。添加端点前应先评估服务边界。

海勒姆定律：用户数量足够多时，总会有人依赖 API 的每一种可观察行为。无论改动多么微小，都可能导致某些用户无法使用。

危险信号

• API 端点接受用户输入，却未进行验证或净化
• 错误响应包含堆栈跟踪或内部路径信息
• 数据库凭据硬编码在源代码中，而非环境变量中
• 面向公众的端点未配置速率限制
• API 在所有失败情况下都返回 200 OK，并在响应正文中包含错误信息
• 使用字符串拼接构建原始 SQL 查询

验证

• 每个端点在处理输入前都会进行验证（展示验证中间件或检查逻辑）
• 错误响应采用标准格式，不包含内部详情（展示错误响应示例）
• 凭据来自环境变量，而非配置文件（搜索硬编码的密钥）
• 公共端点已配置速率限制（展示中间件注册代码）
• 已记录并落实 API 版本管理策略
• 数据库查询使用参数化语句（不使用字符串拼接处理用户输入）
• 所有非公开端点都要求身份验证（展示身份验证中间件）