文档生成

wescode 能够自动生成多种类型的技术文档，从 API 文档到架构设计文档，让文档与代码始终保持同步。

功能概览

能力	说明
API 文档	生成 OpenAPI/Swagger 文档
代码注释	自动添加函数、类型、包级注释
README 生成	项目 README 自动生成和更新
架构文档	生成系统架构设计文档
用户手册	生成面向用户的操作手册

API 文档

从代码生成 API 文档

wescode 分析你的 HTTP handler 代码，自动生成完整的 API 文档：

用户：为整个 API 生成文档

AI：扫描到 23 个 API 端点，生成文档：

  # API 参考文档

  ## 认证
  所有 API 需要在 Header 中携带 `Authorization: Bearer <token>`

  ## 用户管理

  ### 创建用户
  `POST /api/v1/users`

  **请求参数**

  | 字段 | 类型 | 必填 | 说明 |
  |------|------|------|------|
  | username | string | 是 | 用户名，3-32 字符 |
  | email | string | 是 | 邮箱地址 |
  | password | string | 是 | 密码，至少 8 位 |
  | role | string | 否 | 角色，默认 member |

  **成功响应** `201 Created`
  ```json
  {
    "id": "usr_abc123",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "member",
    "created_at": "2026-09-14T10:30:00Z"
  }

错误响应

状态码	错误码	说明
400	VALIDATION_ERROR	参数验证失败
409	CONFLICT	用户名已存在

...（其余端点文档）


### 自动同步

当代码变更时，AI 可以检测文档是否需要更新：

用户：检查哪些 API 文档需要更新

AI：文档同步扫描结果：

需要更新（3 个）： ✗ POST /api/v1/users — 新增了 phone 参数 ✗ GET /api/v1/orders — 返回格式增加了 discount 字段 ✗ DELETE /api/v1/users/:id — 改为软删除，需更新说明

已同步（20 个）： ✓ 其余 API 文档与代码一致

→ 是否自动更新过时的文档？


---

## 代码注释

### 自动添加函数注释

用户：给 internal/service/ 下的所有导出函数添加注释

AI：扫描到 45 个未注释的导出函数，生成注释：

// CreateOrder 创建新订单。 // 它会验证库存、计算价格、生成订单号，并持久化到数据库。 // 如果库存不足，返回 ErrInsufficientStock。 // 如果支付渠道不可用，返回 ErrPaymentUnavailable。 func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderRequest) (*Order, error) { ... }

// GetOrderByID 根据订单 ID 查询订单详情。 // 返回的订单包含关联的订单项（OrderItems）和用户信息。 // 如果订单不存在，返回 ErrOrderNotFound。 func (s *OrderService) GetOrderByID(ctx context.Context, id int64) (*Order, error) { ... }

已处理：45 个函数跳过：12 个函数（已有注释） → 在编辑器中预览所有变更


### 注释风格

AI 会自动匹配项目现有的注释风格：

| 语言 | 注释格式 |
|------|----------|
| Go | `// FuncName verb...` 格式 |
| TypeScript | JSDoc `/** */` 格式 |
| Python | docstring `"""..."""` 格式 |
| Java | Javadoc `/** */` 格式 |
| Rust | `///` 文档注释 |

### 批量处理

用户：给所有没有注释的类型定义添加注释

AI：处理 internal/model/ 下的类型定义：

// Order 表示一个订单实体。 // 对应数据库 orders 表，包含订单的基本信息和状态。 type Order struct { ID int64 json:"id" OrderNo string json:"order_no" // 订单号，格式：YYYYMMDD-XXXXXX UserID int64 json:"user_id" // 下单用户 ID Status OrderStatus json:"status" // 订单状态 TotalAmount decimal.Decimal json:"total_amount" // 订单总金额 // ... }

// OrderStatus 订单状态枚举。 type OrderStatus string

const ( OrderPending OrderStatus = "pending" // 待支付 OrderPaid OrderStatus = "paid" // 已支付 OrderShipped OrderStatus = "shipped" // 已发货 OrderCompleted OrderStatus = "completed" // 已完成 OrderCancelled OrderStatus = "cancelled" // 已取消 )


---

## README 生成

### 项目 README

用户：生成项目 README

AI：生成 README.md：

Project Name

简短的一句话描述项目做什么。

功能特性

✅ 用户管理：注册、登录、权限控制
✅ 订单系统：创建、支付、退款
✅ 通知服务：邮件、短信、站内信
🚧 数据分析：报表生成（开发中）

技术栈

组件	技术
语言	Go 1.22
框架	Gin
数据库	PostgreSQL 16
缓存	Redis 7
消息队列	RabbitMQ

快速开始

前置要求

Go >= 1.22
PostgreSQL >= 16
Redis >= 7

安装

git clone https://github.com/org/project.git
cd project
cp .env.example .env
# 编辑 .env 填入配置
make setup    # 安装依赖、运行迁移
make run      # 启动服务

配置

环境变量	说明	默认值
DB_HOST	数据库地址	localhost
DB_PORT	数据库端口	5432
REDIS_URL	Redis 地址	redis://localhost:6379

项目结构

├── cmd/            # 入口
├── internal/       # 业务逻辑
│   ├── handler/    # HTTP handler
│   ├── service/    # 业务 service
│   ├── repository/ # 数据访问
│   └── model/      # 数据模型
├── migrations/     # 数据库迁移
└── docs/           # 文档

API 文档

启动服务后访问 http://localhost:8080/swagger/index.html

开发

make test     # 运行测试
make lint     # 代码检查
make build    # 构建

License

MIT


### 自动更新 README

当项目结构或技术栈变化时，AI 可以自动更新 README：

用户：更新 README 中的项目结构部分

AI：检测到以下变化：

新增 internal/notification/ 目录
新增 internal/cache/ 目录

删除 internal/legacy/ 目录 → 更新项目结构说明


---

## 架构文档

### 系统架构图

用户：生成系统架构文档

AI：生成 docs/architecture.md：

系统架构

整体架构

┌──────────────────────────────────────────┐
│              客户端层                      │
│   Web App  │  Mobile App  │  API Client   │
└──────┬─────┴──────┬───────┴───────┬───────┘
       │            │               │
┌──────▼────────────▼───────────────▼───────┐
│              API Gateway                   │
│         （认证、限流、路由）                  │
└──────┬────────────┬───────────────┬───────┘
       │            │               │
┌──────▼───┐  ┌─────▼────┐  ┌──────▼───────┐
│ 用户服务  │  │ 订单服务  │  │   通知服务    │
└──────┬───┘  └─────┬────┘  └──────┬───────┘
       │            │               │
┌──────▼────────────▼───────────────▼───────┐
│              数据层                        │
│   PostgreSQL  │  Redis  │  RabbitMQ       │
└───────────────┴─────────┴─────────────────┘

模块依赖

handler → service → repository → database
   ↓         ↓
middleware  cache

数据流

订单创建流程

客户端发送创建订单请求
API Gateway 验证 token，转发到订单服务
订单服务验证库存、计算价格
写入数据库，发送消息到 RabbitMQ
通知服务消费消息，发送订单确认通知
返回订单创建结果

部署架构

...

安全架构

...


### 决策记录（ADR）

用户：记录 "选择 PostgreSQL 而非 MySQL" 的架构决策

AI：生成 docs/decisions/001-database-choice.md：

ADR-001: 选择 PostgreSQL 作为主数据库

状态

已接受（2026-09-14）

上下文

项目需要选择关系型数据库，候选方案：PostgreSQL、MySQL、SQLite。

决定

选择 PostgreSQL 16 作为主数据库。

理由

JSONB 支持：部分业务数据结构灵活，需要半结构化存储
窗口函数：报表统计查询需求复杂
事务隔离：默认 Read Committed + 可序列化隔离级别
扩展生态：PostGIS（地理信息）、pg_vector（向量搜索）

后果

团队需要学习 PostgreSQL 特有语法
运维需要掌握 PostgreSQL 备份和调优
未来如需分库分表，方案选择受限

替代方案

MySQL 8：生态成熟，但 JSONB 支持弱
SQLite：开发简单，但不适合生产多实例部署


---

## 用户手册

### 生成操作手册

用户：为运维人员生成部署手册

AI：生成 docs/operations/deployment.md：

部署手册

前置条件

Linux 服务器（Ubuntu 22.04+ / CentOS 8+）
Docker 24+ 和 Docker Compose v2
至少 2GB 可用内存
至少 10GB 可用磁盘空间

部署步骤

1. 获取部署包

git clone https://github.com/org/project.git
cd project

2. 配置环境变量

cp .env.production.example .env.production
vim .env.production

重要配置项：

变量	说明	示例
DB_HOST	数据库地址	192.168.1.100
DB_PASSWORD	数据库密码	（强密码）
JWT_SECRET	JWT 密钥	（随机生成）

3. 启动服务

docker compose -f docker-compose.prod.yml up -d

4. 验证部署

curl http://localhost:8080/health
# 期望返回 {"status": "ok"}

日常运维

查看日志

docker compose logs -f --tail=100 app

备份数据库

./scripts/backup.sh
# 备份文件保存在 /data/backups/

更新版本

git pull
docker compose -f docker-compose.prod.yml up -d --build

故障排查

...

监控告警

...


---

## 文档管理

### 文档完整性检查

用户：检查文档完整性

AI：文档完整性报告：

API 文档覆盖率：85% ├── ✓ 已覆盖：20 个端点 ├── ✗ 缺失：3 个端点 │ - POST /api/v1/orders/:id/refund │ - GET /api/v1/reports/daily │ - PUT /api/v1/settings └── ⚠ 过时：2 个端点需要更新

代码注释覆盖率：72% ├── 导出函数：68/94 已注释 ├── 导出类型：15/18 已注释 └── 包文档：8/12 已编写

项目文档： ├── ✓ README.md — 完整 ├── ✓ CONTRIBUTING.md — 完整 ├── ✗ CHANGELOG.md — 缺失 ├── ✓ LICENSE — 完整 └── ⚠ docs/architecture.md — 需要更新


---

## 注意事项

- 自动生成的文档是起点，需要人工审阅和完善
- API 文档中的示例数据不应包含真实用户信息
- 架构文档应随重大变更及时更新
- README 中的命令和配置示例需要可实际运行
- 注释应解释"为什么"而非"做什么"——显而易见的代码不需要注释