feat: scaffold codespace backend

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 15:07:54 +08:00
commit 411ed1f8ba
43 changed files with 4428 additions and 0 deletions
@@ -0,0 +1,287 @@
+# Gin Router and Explicit HTTP Server Composition Design
+
+日期：2026-07-02
+
+## 目标
+
+将 codespace 后端的原生 Go 1.22 `http.ServeMux` 路由替换为 Gin，同时继续显式构造 `http.Server`。Gin 只负责路由和 handler 上下文，网络层仍由 `http.Server` 控制。
+
+本次改动的核心要求：
+
+- 使用 Gin 注册 API 路由。
+- 不使用 `router.Run()` 或 `engine.Run()`。
+- 将 `*gin.Engine` 显式设置为 `http.Server.Handler`。
+- 将服务器网络参数配置化，包括 timeout 和最大请求头大小。
+- 保持现有 API 路径、HTTP method、响应 JSON 结构不变。
+
+## 当前状态
+
+当前代码：
+
+- `cmd/server/main.go` 已显式构造 `http.Server`。
+- `internal/api/router.go` 使用 `http.NewServeMux()`。
+- handler 使用 `http.ResponseWriter`、`*http.Request`、`r.PathValue("id")` 和 `json.NewDecoder(r.Body)`。
+- `pkg/config` 只配置 `server.addr`，timeout 仍硬编码在 `main.go`。
+
+## 非目标
+
+本次不做：
+
+- 不引入认证、CORS、rate limit、request logger middleware。
+- 不改变 workspace/file/process service 接口。
+- 不改变 API 路径、HTTP method、响应结构。
+- 不实现 WebSocket、watcher 推送、Git、LSP、AI Agent。
+- 不把网络层控制权交给 Gin 的 `Run()`。
+
+## 目标架构
+
+```text
+cmd/server/main.go
+  ↓
+config.Load()
+  ↓
+api.NewRouter(...)
+  ↓
+*gin.Engine
+  ↓
+http.Server{
+    Addr,
+    Handler: ginEngine,
+    ReadTimeout,
+    WriteTimeout,
+    IdleTimeout,
+    MaxHeaderBytes,
+}
+  ↓
+ListenAndServe()
+```
+
+关键规则：
+
+1. `internal/api.NewRouter` 返回 `*gin.Engine`。
+2. `cmd/server/main.go` 显式创建 `http.Server`。
+3. `http.Server.Handler` 设置为 Gin engine。
+4. 代码中不得出现 `.Run(` 用于启动 Gin server。
+5. `ReadTimeout`、`WriteTimeout`、`IdleTimeout`、`MaxHeaderBytes` 来自配置。
+
+## 配置设计
+
+`configs/config.yaml` 扩展为：
+
+```yaml
+server:
+  addr: ":8080"
+  readTimeout: "15s"
+  writeTimeout: "15s"
+  idleTimeout: "60s"
+  maxHeaderBytes: 1048576
+workspace:
+  root: "./workspaces"
+process:
+  opencodeCommand: "opencode"
+```
+
+`pkg/config.ServerConfig` 对外使用强类型：
+
+```go
+type ServerConfig struct {
+    Addr           string
+    ReadTimeout    time.Duration
+    WriteTimeout   time.Duration
+    IdleTimeout    time.Duration
+    MaxHeaderBytes int
+}
+```
+
+YAML 加载不要依赖 `time.Duration` 的隐式解析。使用 raw config 字符串字段承接 YAML，然后通过 `time.ParseDuration` 显式解析。这样 `"15s"`、`"1m"`、`"500ms"` 都清晰可控。
+
+环境变量增加：
+
+- `CODESPACE_READ_TIMEOUT`
+- `CODESPACE_WRITE_TIMEOUT`
+- `CODESPACE_IDLE_TIMEOUT`
+- `CODESPACE_MAX_HEADER_BYTES`
+
+已有环境变量保持不变：
+
+- `CODESPACE_ADDR`
+- `CODESPACE_WORKSPACE_ROOT`
+- `CODESPACE_OPENCODE_COMMAND`
+
+默认值：
+
+- `addr`: `:8080`
+- `readTimeout`: `15s`
+- `writeTimeout`: `15s`
+- `idleTimeout`: `60s`
+- `maxHeaderBytes`: `1048576`
+
+## 路由设计
+
+原路由保持不变：
+
+```text
+GET    /healthz
+POST   /api/workspaces
+GET    /api/workspaces/:id
+DELETE /api/workspaces/:id
+GET    /api/workspaces/:id/files
+GET    /api/workspaces/:id/files/read
+PUT    /api/workspaces/:id/files/write
+POST   /api/workspaces/:id/files/mkdir
+DELETE /api/workspaces/:id/files
+POST   /api/workspaces/:id/files/rename
+POST   /api/workspaces/:id/process/start
+POST   /api/workspaces/:id/process/stop
+POST   /api/workspaces/:id/process/restart
+GET    /api/workspaces/:id/process/status
+```
+
+Gin 注册方式：
+
+```go
+r := gin.New()
+r.GET("/healthz", healthHandler)
+api := r.Group("/api")
+api.POST("/workspaces", workspaceHandler.create)
+api.GET("/workspaces/:id", workspaceHandler.get)
+```
+
+第一版使用 `gin.New()` 而不是 `gin.Default()`，避免隐式加入 logger middleware。只添加 `gin.Recovery()`，防止 panic 打爆进程。请求日志以后有真实需求再加。
+
+## Handler 迁移
+
+签名从：
+
+```go
+func (h *workspaceHandler) get(w http.ResponseWriter, r *http.Request)
+```
+
+改为：
+
+```go
+func (h *workspaceHandler) get(c *gin.Context)
+```
+
+路径参数：
+
+```go
+id := c.Param("id")
+```
+
+查询参数：
+
+```go
+path := c.Query("path")
+```
+
+JSON body：
+
+```go
+if err := c.ShouldBindJSON(&req); err != nil {
+    writeError(c, util.New(util.CodeBadRequest, "invalid json"))
+    return
+}
+```
+
+响应：
+
+```go
+c.JSON(http.StatusCreated, model.WorkspaceResponse{ID: ws.ID})
+c.Status(http.StatusNoContent)
+```
+
+## 错误处理
+
+保持现有错误 JSON：
+
+```json
+{
+  "error": {
+    "code": "bad_request",
+    "message": "invalid json"
+  }
+}
+```
+
+`internal/api/errors_helper.go` 改为接收 `*gin.Context`：
+
+```go
+func writeError(c *gin.Context, err error)
+```
+
+继续使用 `util.CodeOf(err)` 映射：
+
+- `bad_request` -> 400
+- `not_found` -> 404
+- `conflict` -> 409
+- default -> 500
+
+可以复用 `pkg/response.ErrorBody` 和 `pkg/response.ErrorDetail`，避免重复定义响应结构。
+
+## Server 组合
+
+`cmd/server/main.go` 最终保持显式组合：
+
+```go
+router := api.NewRouter(workspaceSvc, fileSvc, processSvc)
+server := &http.Server{
+    Addr:           cfg.Server.Addr,
+    Handler:        router,
+    ReadTimeout:    cfg.Server.ReadTimeout,
+    WriteTimeout:   cfg.Server.WriteTimeout,
+    IdleTimeout:    cfg.Server.IdleTimeout,
+    MaxHeaderBytes: cfg.Server.MaxHeaderBytes,
+}
+```
+
+启动仍然使用：
+
+```go
+server.ListenAndServe()
+```
+
+## 测试策略
+
+现有 `httptest` 测试继续有效，因为 `*gin.Engine` 实现 `http.Handler`。
+
+需要验证：
+
+- `GET /healthz` 行为不变。
+- workspace 创建、文件写读、process status 行为不变。
+- Gin path param `:id` 正常传入 service。
+- 配置默认值正确。
+- YAML timeout 字符串能解析。
+- 环境变量能覆盖 timeout 和 `maxHeaderBytes`。
+- `go test ./...` 通过。
+- `grep -R "\.Run(" cmd internal || true` 无输出。
+- `go run ./cmd/server` 后 `/healthz` 返回 `{"status":"ok"}`。
+
+## 依赖
+
+新增唯一依赖：
+
+```text
+github.com/gin-gonic/gin
+```
+
+不新增其他框架或中间件依赖。
+
+## 风险与处理
+
+- 风险：Gin 默认模式可能输出 debug 信息。处理：启动时可设置 `gin.SetMode(gin.ReleaseMode)`，或保留 Gin 默认但不影响功能。第一版建议在 `NewRouter` 中设置 `gin.ReleaseMode`，减少噪音。
+- 风险：`time.Duration` YAML 解析行为不符合预期。处理：使用 raw string + `time.ParseDuration`。
+- 风险：错误响应格式变化。处理：复用现有响应结构并保留 HTTP 测试。
+- 风险：误用 `router.Run()`。处理：增加 grep 验证。
+
+## 完成标准
+
+完成后必须满足：
+
+- `internal/api` 使用 Gin 注册路由。
+- `cmd/server/main.go` 使用 `http.Server{Handler: router}`。
+- 不出现 Gin `Run()` 启动服务器。
+- server 网络参数来自配置。
+- API 行为和响应结构保持兼容。
+- `go test ./...` 通过。
+- server smoke test 通过。