# P0: 生产可用性特性设计

日期: 2026-06-11
状态: Approved

## 概述

5 个独立特性，使 lolly 达到生产可部署状态。所有特性互不依赖，可完全并行开发。

---

## 1. CORS 中间件

### 配置

在 `security.cors` 下新增 `CORSConfig` 结构体，server 级别配置：

```yaml
security:
  cors:
    enabled: true
    allowed_origins: ["https://example.com", "https://api.example.com"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allowed_headers: ["Content-Type", "Authorization", "X-Request-ID"]
    expose_headers: ["X-Total-Count"]
    allow_credentials: true
    max_age: 3600
```

字段说明：
- `enabled`: 启用开关（默认 false）
- `allowed_origins`: 允许的源列表，支持 `"*"` 通配（与 `allow_credentials: true` 互斥，遵循 CORS 规范）
- `allowed_methods`: 允许的 HTTP 方法
- `allowed_headers`: 允许的请求头
- `expose_headers`: 允许前端读取的响应头
- `allow_credentials`: 是否允许发送 Cookie
- `max_age`: preflight 缓存时间（秒），默认 0

### 文件

| 文件 | 操作 |
|------|------|
| `internal/middleware/cors/cors.go` | 新建：CORS 中间件实现 |
| `internal/middleware/cors/cors_test.go` | 新建：单元测试 |
| `internal/config/security_config.go` | 修改：添加 `CORSConfig` 结构体 |
| `internal/config/defaults.go` | 修改：CORS 默认值
| `internal/config/validate.go` | 修改：CORS 验证（origins+credentials 互斥检查）
| `internal/server/middleware_builder.go` | 修改：注册 CORS 中间件（步骤 7.5，SecurityHeaders 之后、ErrorIntercept 之前）

### 行为

1. 非 CORS 请求（无 `Origin` 头）：直接 pass-through
2. Preflight (OPTIONS)：返回 204 + CORS 头，不进入后续 handler
3. 实际请求：调用 `next(ctx)` 后添加 CORS 响应头
4. Origin 不匹配：不加 CORS 头，浏览器阻止跨域

---

## 2. Request-ID 传播

### 配置

无需额外配置，默认启用。

### 文件

| 文件 | 操作 |
|------|------|
| `internal/middleware/requestid/requestid.go` | 新建：Request-ID 中间件 |
| `internal/middleware/requestid/requestid_test.go` | 新建：单元测试 |
| `internal/proxy/headers.go` | 修改：`SetForwardedHeaders` 添加 X-Request-ID 传播 |
| `internal/server/middleware_builder.go` | 修改：注册为第一个中间件（AccessLog 之前）

### 行为

1. 检查入站 `X-Request-ID` 请求头
2. 有值 → 复用（信任下游），存入 `ctx.SetUserValue("request_id", id)`
3. 无值 → 生成 UUID v4，存入 `ctx.SetUserValue`
4. 始终在响应中设置 `X-Request-ID` 头
5. 代理转发时，`SetForwardedHeaders` 自动传播 `X-Request-ID`（从 `ctx.UserValue("request_id")` 读取）

### 与现有代码的关系

`internal/variable/builtin.go` 已有 `$request_id` 变量，会从 `ctx.UserValue("request_id")` 读取。中间件在请求早期设置此值后，变量系统、access log、proxy header forwarding 都能正确使用。

---

## 3. /healthz + /readyz 端点

### 配置

在 `monitoring` 下新增：

```yaml
monitoring:
  healthz:
    enabled: true
    path: "/healthz"
  readyz:
    enabled: true
    path: "/readyz"
```

字段说明：
- `enabled`: 默认 true（开箱即用）
- `path`: 可自定义路径

### 文件

| 文件 | 操作 |
|------|------|
| `internal/server/healthz.go` | 新建：healthz/readyz handler |
| `internal/server/healthz_test.go` | 新建：单元测试 |
| `internal/config/monitoring_config.go` | 修改：添加 `HealthzConfig`、`ReadyzConfig` |
| `internal/config/defaults.go` | 修改：默认值
| `internal/server/server.go` | 修改：注册端点（三种模式都需要） |

### 行为

**healthz（存活探针）**：
- GET → 200 `{"status":"ok"}`
- 无任何依赖检查，只要进程活着就返回 200

**readyz（就绪探针）**：
- GET → 200 `{"status":"ready"}` 或 503 `{"status":"not ready","reasons":["no healthy upstreams"]}`
- 检查条件：至少有一个 server 已启动 + 至少有一个 upstream 目标可用（如果有配置 proxy 的话）
- 无 proxy 配置的纯静态文件服务器永远返回 200

### 注册位置

与 status/pprof 同级：
- Single 模式：`locationEngine.AddExact`
- VHost/Multi 模式：`router.GET`

默认启用，不需要 IP 白名单（K8s 探针来自 kubelet）。

---

## 4. 环境变量插值

### 语法

仅 `${ENV_VAR}` 花括号语法，与 lolly 自身 `$variable` 系统无歧义。

缺失环境变量时保留原样（`${MISSING_VAR}` 不展开）。

### 文件

| 文件 | 操作 |
|------|------|
| `internal/config/env.go` | 新建：`ExpandEnv(data []byte) []byte` 函数 |
| `internal/config/env_test.go` | 新建：单元测试 |
| `internal/config/config.go` | 修改：`Load()` 和 `processIncludes()` 中调用 `ExpandEnv` |

### 实现

正则 `\$\{([^}]+)\}` 匹配：
- 匹配到 → `os.Getenv(key)`
- 环境变量存在 → 替换为值
- 环境变量不存在 → 保留 `${key}` 原样

调用位置：
1. `Load()`: `os.ReadFile` 之后、`yaml.Unmarshal` 之前
2. `processIncludes()`: 每个被 include 文件 `os.ReadFile` 之后、`yaml.Unmarshal` 之前

### 示例

```yaml
servers:
  - listen: "${LISTEN_ADDR}:8080"
    ssl:
      cert: "${SSL_CERT_PATH}"
      key: "${SSL_KEY_PATH}"
    security:
      auth:
        users:
          - name: admin
            password: "${ADMIN_PASSWORD_HASH}"
```

---

## 5. CI/CD 流水线

### 配置

`.github/workflows/ci.yml` 单文件，push to master + PR 触发。

### Jobs

| Job | 依赖 | 步骤 |
|-----|------|------|
| `lint` | 无 | gofumpt 检查 → golangci-lint |
| `test` | 无 | `go test -race ./internal/...` |
| `build` | lint + test | 多平台静态构建（linux/amd64, linux/arm64, darwin/amd64, darwin/arm64） |
| `docker` | build（仅 push/tag） | docker build + push |

### 文件

| 文件 | 操作 |
|------|------|
| `.github/workflows/ci.yml` | 新建：GitHub Actions CI 流水线 |

### 约束

- Go 1.26
- `CGO_ENABLED=0`
- E2E 测试需要 Docker service（testcontainers）
- 使用 `make fmt`、`make lint`、`make test` 命令

---

## 依赖关系

```
CORS ──────┐
Request-ID ┤── 全部独立，可并行
healthz ───┤
env interp ┤
CI/CD ─────┘
```

## 提交策略

每个特性一个独立 commit：
1. `feat(middleware/cors): add CORS middleware with server-level config`
2. `feat(middleware/requestid): add request ID generation and propagation`
3. `feat(server): add /healthz and /readyz endpoints for k8s probes`
4. `feat(config): add ${ENV_VAR} interpolation in YAML config`
5. `ci: add GitHub Actions CI pipeline`