2. 自助门户架构设计

自助门户是平台工程中发布工程的核心交互界面，其架构设计直接决定了开发者的使用体验、平台的扩展性以及运维的复杂度。本章节从前端技术选型、后端API设计原则、数据库选型三个维度展开，并最终通过整体架构图串联各组件关系。

2.1 前端技术选型：React vs Vue

前端框架的选择需综合考虑团队技术栈、生态成熟度、组件库丰富度以及长期维护成本。在平台工程场景下，门户通常需要处理复杂的表单、动态配置、实时状态更新以及多步骤向导，这对框架的响应式能力和状态管理提出了较高要求。

2.2 后端API设计原则

自助门户的后端API是连接前端与底层基础设施的桥梁，设计质量直接影响前端开发效率与系统可维护性。以下为核心设计原则：

1. RESTful 风格为主，GraphQL 为辅：对于资源型操作（环境列表、部署记录、配置详情）采用 RESTful 接口，清晰直观；对于复杂查询或动态字段选择（如环境编排参数组合），可引入 GraphQL 端点，减少前端数据冗余。
2. 版本化与向后兼容：所有API必须携带版本号（如 /api/v1/environments），避免破坏性变更影响已有客户端。废弃端点需提供明确的迁移周期与响应头警告。
3. 统一响应格式：所有接口返回统一结构，便于前端统一处理错误与加载状态。

{
  "code": 0,                // 0 表示成功，非0表示业务错误码
  "message": "success",
  "data": { ... },          // 实际业务数据
  "requestId": "a1b2c3d4"   // 用于链路追踪
}

4. 幂等性与原子操作：环境创建、部署触发等关键操作必须支持幂等性，通过客户端请求ID或业务唯一键去重，防止重复提交导致资源异常。
5. 细粒度权限校验：每个API端点需校验用户对特定环境、项目或集群的操作权限，避免越权访问。推荐使用RBAC + 资源级权限模型。
6. 异步任务与状态轮询：对于耗时操作（如环境编排、部署流水线），API应返回任务ID，前端通过轮询或WebSocket获取任务状态，避免HTTP长连接阻塞。

2.3 数据库选型：PostgreSQL vs MySQL

自助门户的数据库需要存储环境元数据、部署记录、配置快照、用户权限等结构化数据，同时可能涉及JSON字段存储动态配置。选型时需关注事务支持、扩展能力、JSON处理性能以及生态工具链。

2.4 整体架构图

以下SVG图展示了自助门户的整体架构，涵盖前端、后端、数据库、基础设施层以及关键交互流程。

2.5 架构分层说明

整体架构采用经典的四层设计，各层职责清晰，便于团队分工与独立迭代：

• 前端展示层：负责用户交互、表单渲染、状态展示。通过WebSocket接收后端推送的实时状态，提升用户体验。
• API网关层：统一入口，处理跨域、限流、鉴权、请求转发。网关层可集成OAuth2/OIDC认证，保障API安全。
• 后端微服务层：按业务领域拆分为环境编排、部署配置、权限管理、审计日志等独立服务。服务间通过gRPC或消息队列通信，避免直接HTTP耦合。
• 数据与基础设施层：PostgreSQL存储持久化数据，Redis提供缓存与实时状态通道。基础设施编排层通过Kubernetes API或Terraform驱动底层资源。

2.6 关键交互流程：环境创建请求

以下SVG图展示了用户通过自助门户发起环境创建请求的完整交互流程，帮助理解各层协作关系。