# rs-zero 文档总览

这份目录按使用路径组织文档，优先帮助新手快速跑通项目，再进入模块手册和生产实践。

## 新手上手

1. [快速开始](getting-started.md)：安装前置条件、验证 workspace、运行 REST/RPC 示例、使用 CLI 生成 skeleton。
2. [REST 服务教程](tutorials/rest-service.md)：理解 `rs-zero` 的 `rest` feature、统一响应、错误和默认服务边界。
3. [API codegen 教程](tutorials/api-codegen.md)：用 `.api` 文件验证、格式化、导出 OpenAPI、生成 REST skeleton。
4. [RPC 服务教程](tutorials/rpc-service.md)：运行 tonic health 示例，了解 proto skeleton 生成边界。
5. [Model/cache 教程](tutorials/model-cache.md)：从 SQL schema 生成 entity、SQLx repository、cache key helper 和 cache-aside repository。

## 用户手册

- [CLI 手册](manual/cli.md)
- [REST 手册](manual/rest.md)
- [RPC 手册](manual/rpc.md)
- [Service group 手册](manual/service-group.md)
- [Resilience 手册](manual/resilience.md)
- [API DSL 手册](manual/api-dsl.md)
- [Model/cache 手册](manual/model-cache.md)
- [Cache 手册](manual/cache.md)
- [Redis 生产配置](redis.md)
- [Distributed lock 手册](manual/distributed-lock.md)
- [Discovery 手册](manual/discovery.md)
- [Observability 手册](manual/observability.md)
- [Production adapters 手册](manual/production-adapters.md)
- [goctl compatibility 手册](manual/goctl-compatibility.md)

## 生产与维护

- [最佳实践](best-practices.md)
- [排障手册](troubleshooting.md)
- [生产检查清单](production-checklist.md)
- [部署说明](deployment.md)
- [生产 adapters](production-adapters.md)
- [External integration CI](external-integration-ci.md)
- [压力、故障与长跑测试](stress-testing.md)
- [观测能力](observability.md)

## 稳定性、兼容性与路线图

- [API 稳定性](api-stability.md)
- [Feature matrix](feature-matrix.md)
- [迁移指南](migrations/README.md)
- [go-zero 能力映射](go-zero-mapping.md)
- [goctl 兼容矩阵](goctl-compatibility.md)
- [MVP roadmap](mvp-roadmap.md)

## 文档维护规则

- 文档描述必须以代码和测试为准。
- 命令示例优先使用仓库内 `examples/`、`tests/` 和 `rs-zero-cli` 已实现子命令。
- 新增文档必须使用相对链接，不能包含本地绝对路径、真实凭据或私有 endpoint。
- 提交前运行 `cargo test --test docs_links` 检查文档链接和敏感模式。
