操作指南

操作指南

这些指南是实用配方。每篇针对单一任务，展示完成任务所需的最少代码，并在需要边界原理时链接到相关的模块 primer。

阅读前提：已完成 开始使用 并能运行参考服务。 如果你是第一次进入项目，先完成文档首页上的前 30 分钟路径，再选择具体指南。

可用指南

稳定根模式

指南	内容
添加 JWT 认证	用 security/jwt + middleware/auth 保护路由
编写自定义 Middleware	实现带显式依赖的 middleware.Middleware 构造函数
连接数据库	无全局变量地将 store 基础元语注入 handler
处理错误	用 contract.WriteError 和 NewErrorBuilder 返回结构化响应
优雅关闭	将 OS 信号处理与 Prepare / Server / Shutdown 生命周期结合
健康检查与就绪检查	实现 ComponentChecker 并注册 /healthz + /readyz
结构化日志	在 handler 和 middleware 中使用 log.NewLogger、WithFields 和 Fields
测试 Handler	用 httptest.NewRecorder 测试 http.HandlerFunc handler

扩展能力

指南	内容
接入 AI	接入 x/ai provider、管理会话，并通过 SSE 流式返回补全
构建 REST 资源	使用 x/rest 实现完整 CRUD，包含分页、过滤和 SQL 仓储
多租户	用 x/tenant 解析租户身份、执行策略并限定数据查询范围
实时通信 WebSocket	使用 x/websocket 升级连接、管理房间和 Hub、广播消息
文件上传与下载	使用 x/fileapi handler 实现分片上传、流式下载和文件元数据

运维与生命周期

指南	内容
Docker 部署	多阶段 Dockerfile、环境变量配置、Kubernetes 健康探针
可观测性集成	Prometheus 指标、结构化日志、通过 x/observability 的分布式追踪
迁移与升级	稳定根升级路径、追踪实验性到 stable 的晋升

指南的范围说明

每篇指南展示一种正确模式并就此停止。它们不尝试覆盖每个选项或配置旋钮 — 模块 primer 和源码树中的 module.yaml 文件负责那部分内容。如果指南代码与模块的 module.yaml 有出入，module.yaml 是权威来源。

稳定根指南不会将 x/* 扩展引入规范服务路径。运维指南在该能力的正确归属是 x/observability 时会引用它——每次引用都链接到扩展 primer 以说明边界原理。