arch-engineering

name

arch-engineering

description

全栈工程实践：项目分层与三层架构、配置管理、错误处理、数据库访问、缓存、实时通信、API 设计与治理、认证与授权架构、环境与配置管理、云原生基础设施、技术选型评估。 TRIGGER when: 全栈架构设计、前后端集成、项目分层、Feature-first 结构、依赖注入、类型化错误体系、N+1 查询、缓存模式、SSE/WebSocket、REST/GraphQL/gRPC/tRPC 选型、API 版本化、契约管理、JWT/Session/OAuth2、RBAC、中间件顺序、CORS、多环境策略、K8s 决策、服务网格、多区域部署、IaC、技术选型评估、可观测性建设、OpenTelemetry、日志规范、指标埋点、链路追踪、事件驱动架构、消息队列选型、Kafka/RabbitMQ、事件溯源、Transactional Outbox、CDC。 DO NOT TRIGGER when: 架构选型（用 arch-design）、方案评审（用 arch-review）、架构演进规划（用 arch-evolution）。

全栈工程实践

目标

为全栈架构设计和工程实现提供实践指南，确保项目分层清晰、配置管理规范、错误处理类型化、API 契约稳定、认证架构安全、环境配置可管理。

工作流

1. 全栈开发架构实践

项目结构（Feature-first）、三层架构（Controller→Service→Repository）、依赖注入（TS/Python/Go）、错误处理体系、数据库访问模式（N+1/事务/连接池）、缓存模式、后台任务、实时通信、反模式速查表见： references/fullstack-practices.md

配置管理、环境变量校验、.env.example 规范和 CORS 配置见： references/environment-management.md

2. API 设计与治理

API 风格选型（REST/GraphQL/gRPC/tRPC 决策树）、REST 设计规范、版本化与向后兼容、API 网关与 BFF 模式、OpenAPI 契约管理见： references/api-governance.md

3. 认证与授权架构

JWT vs Session 决策、JWT Bearer 流程、Token 自动刷新、RBAC 四层权限检查、中间件 10 步顺序、OAuth2/OIDC 授权码流程见： references/auth-flow.md

4. 云原生基础设施

K8s 命名空间划分与资源管理、服务网格选型（Linkerd/Istio/Cilium）、多区域多活部署、IaC 模块化、云成本优化见： references/cloud-native-infra.md

5. 技术选型评估

6 维度评估矩阵（成熟度/团队匹配/生态/运维/性能/退出成本）、语言/框架/数据库/基础设施选型、Build vs Buy 决策见： references/technology-selection.md

6. 可观测性建设

OpenTelemetry 集成、结构化日志规范、指标埋点（RED/USE）、Trace 串联、告警分级、仪表盘见： references/observability.md

7. 事件/消息平台

消息中间件选型（Kafka/RabbitMQ/NATS/Pulsar）、事件命名规范、Schema 演进、Transactional Outbox、CDC、幂等消费、死信队列、事件溯源见： references/event-platform.md

决策规则

• 按 FEATURE 组织代码，不按技术层
• Controller 不含业务逻辑，Service 不导入 HTTP 类型
• 所有配置走环境变量，启动校验，快速失败
• 每个错误都有类型，全局处理，统一格式
• 所有输入在边界校验——不信任客户端
• 技术选型含 6 维度评估矩阵和退出策略，不只说"用这个"