从零开始系统学习 Go 编程

Appearance

6.7 文档生成 ​

godoc 注释规范 ​

基础注释 ​

go
// Package main 提供应用程序入口
package main

import "fmt"

// User 表示用户信息
type User struct {
    ID    string // 用户唯一标识
    Name  string // 用户姓名
    Email string // 电子邮箱
}

// UserService 提供用户相关服务
type UserService struct {
    repo UserRepository
}

// NewUserService 创建新的用户服务
// 参数:
//   - repo: 用户数据仓库
// 返回:
//   - *UserService: 用户服务实例
func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

// GetUser 根据 ID 获取用户
// 参数:
//   - ctx: 上下文
//   - id: 用户 ID
// 返回:
//   - *User: 用户信息
//   - error: 错误信息
// 示例:
//   user, err := service.GetUser(ctx, "123")
//   if err != nil {
//       log.Fatal(err)
//   }
func (s *UserService) GetUser(ctx context.Context, id string) (*User, error) {
    return s.repo.GetByID(id)
}

// String 返回用户的字符串表示
func (u *User) String() string {
    return fmt.Sprintf("User{%s, %s}", u.ID, u.Name)
}

// ErrUserNotFound 用户不存在错误
var ErrUserNotFound = errors.New("user not found")

// CreateUser 创建新用户
// 注意：创建前会验证邮箱格式
// BUG: 当邮箱已存在时返回模糊错误
func (s *UserService) CreateUser(ctx context.Context, name, email string) (*User, error) {
    // ...
}

注释最佳实践 ​

go
// 好：简洁明了
// ParseInt 将字符串解析为整数
func ParseInt(s string) (int, error) { }

// 不好：重复函数名
// ParseInt 解析整数的函数
func ParseInt(s string) (int, error) { }

// 好：说明行为
// Close 关闭连接并释放资源
func (c *Conn) Close() error { }

// 不好：无意义
// Close 关闭东西
func (c *Conn) Close() error { }

// 好：包含示例
// Double 返回输入的两倍
// 例如：Double(3) = 6
func Double(x int) int { return x * 2 }

Go Doc 生成 ​

本地查看文档 ​

bash
# 启动 godoc 服务器
godoc -http=:6060

# 访问 http://localhost:6060/pkg/your-module

# 命令行查看
go doc fmt
go doc fmt.Println
go doc -all fmt          # 查看完整文档
go doc -src fmt.Println  # 查看源码

生成静态文档 ​

bash
# 安装 pkgsite
go install golang.org/x/pkgsite/cmd/pkgsite@latest

# 生成本地文档
pkgsite -http=localhost:8080

# 生成文档到目录
pkgsite -generate ./... -outdir ./docs

Swagger/OpenAPI ​

swag 安装与初始化 ​

bash
# 安装 swag
go install github.com/swaggo/swag/cmd/swag@latest

# 初始化
swag init

# 指定主文件
swag init -g cmd/main.go

# 输出到指定目录
swag init -g cmd/main.go -o ./docs

# 生成时解析依赖包
swag init -g cmd/main.go --parseDependency

# 生成时解析内部包
swag init -g cmd/main.go --parseInternal

API 注释 ​

go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

// @title          用户管理 API
// @version        1.0.0
// @description    用户管理系统的 RESTful API
// @termsOfService http://swagger.io/terms/

// @contact.name   API Support
// @contact.email  support@example.com

// @license.name   MIT
// @license.url    https://opensource.org/licenses/MIT

// @host         api.example.com
// @BasePath     /api/v1

// @securityDefinitions.apikey  BearerAuth
// @in                          header
// @name                        Authorization
// @description                 使用 JWT token，格式：Bearer {token}

// User 用户信息
// @description 用户数据模型
type User struct {
    ID    string `json:"id" example:"123"`
    Name  string `json:"name" example:"张三"`
    Email string `json:"email" example:"zhangsan@example.com"`
    Age   int    `json:"age" example:"25"`
}

// CreateUserRequest 创建用户请求
type CreateUserRequest struct {
    Name  string `json:"name" binding:"required" example:"张三"`
    Email string `json:"email" binding:"required,email" example:"zhangsan@example.com"`
    Age   int    `json:"age" binding:"min=0,max=150" example:"25"`
}

// CreateUser godoc
// @Summary      创建用户
// @Description  创建一个新的用户账号
// @Tags         用户
// @Accept       json
// @Produce      json
// @Param        request  body      CreateUserRequest  true  "用户信息"
// @Success      200      {object}  User
// @Failure      400      {object}  ErrorResponse
// @Failure      401      {object}  ErrorResponse
// @Failure      500      {object}  ErrorResponse
// @Security     BearerAuth
// @Router       /users [post]
func (h *Handler) CreateUser(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }

    user := &User{
        Name:  req.Name,
        Email: req.Email,
        Age:   req.Age,
    }

    c.JSON(200, user)
}

// GetUser godoc
// @Summary      获取用户
// @Description  根据 ID 获取用户信息
// @Tags         用户
// @Accept       json
// @Produce      json
// @Param        id   path      string  true  "用户 ID"
// @Success      200  {object}  User
// @Failure      404  {object}  ErrorResponse
// @Security     BearerAuth
// @Router       /users/{id} [get]
func (h *Handler) GetUser(c *gin.Context) {
    id := c.Param("id")
    // ...
}

// ListUsers godoc
// @Summary      用户列表
// @Description  获取用户列表，支持分页和搜索
// @Tags         用户
// @Accept       json
// @Produce      json
// @Param        page     query     int     false  "页码"     default(1)
// @Param        limit    query     int     false  "每页数量" default(20)
// @Param        keyword  query     string  false  "搜索关键字"
// @Success      200      {array}   User
// @Security     BearerAuth
// @Router       /users [get]
func (h *Handler) ListUsers(c *gin.Context) {
    // ...
}

// DeleteUser godoc
// @Summary      删除用户
// @Description  删除指定用户
// @Tags         用户
// @Accept       json
// @Produce      json
// @Param        id   path      string  true  "用户 ID"
// @Success      204
// @Failure      404  {object}  ErrorResponse
// @Security     BearerAuth
// @Router       /users/{id} [delete]
func (h *Handler) DeleteUser(c *gin.Context) {
    // ...
}

// ErrorResponse 错误响应
type ErrorResponse struct {
    Error   string `json:"error"`
    Message string `json:"message"`
}

集成到 Gin ​

go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func main() {
    r := gin.Default()

    // Swagger UI
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // API 路由
    api := r.Group("/api/v1")
    {
        api.POST("/users", handler.CreateUser)
        api.GET("/users/:id", handler.GetUser)
        api.GET("/users", handler.ListUsers)
        api.DELETE("/users/:id", handler.DeleteUser)
    }

    r.Run(":8080")
}

// 在 main 函数中添加
// @securityDefinitions.apikey  BearerAuth
// @in                          header
// @name                        Authorization

生成的文件 ​

docs/
├── docs.go           // Go 初始化的文档
├── swagger.json      // OpenAPI/Swagger JSON
└── swagger.yaml      // OpenAPI/Swagger YAML

API 文档自动化 ​

在 CI 中生成文档 ​

yaml
# .github/workflows/docs.yml
name: Generate Docs

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'

      - name: Install swag
        run: go install github.com/swaggo/swag/cmd/swag@latest

      - name: Generate docs
        run: swag init -g cmd/main.go -o ./docs

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

README 编写规范 ​

标准结构 ​

markdown
# 项目名称

简短的项目描述。

[![Go Report Card](https://goreportcard.com/badge/github.com/user/repo)](https://goreportcard.com/report/github.com/user/repo)
[![Tests](https://github.com/user/repo/actions/workflows/test.yml/badge.svg)](https://github.com/user/repo/actions/workflows/test.yml)
[![GoDoc](https://pkg.go.dev/badge/github.com/user/repo)](https://pkg.go.dev/github.com/user/repo)

## 安装

```bash
go get github.com/user/repo

快速开始 ​

go
package main

import "github.com/user/repo"

func main() {
    // 使用示例
}

功能特性 ​

  • 特性 1
  • 特性 2
  • 特性 3

文档 ​

示例 ​

查看 examples/ 目录获取更多示例。

贡献 ​

欢迎提交 Issue 和 Pull Request!

许可证 ​

MIT License


---

## CHANGELOG 管理

### Keep a Changelog 格式

```markdown
# Changelog

所有重要的项目变更都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
项目遵循 [语义化版本](https://semver.org/spec/v2.0.0.html)。

## [Unreleased]

### Added
- 新增用户批量导入功能

### Changed
- 优化数据库查询性能

### Deprecated
- 旧版 API 端点 `/api/v1/legacy`

### Removed
- 移除已废弃的配置项

### Fixed
- 修复用户删除时的并发问题

### Security
- 升级依赖修复 CVE-2024-XXXX

## [1.0.0] - 2024-01-15

### Added
- 初始版本发布
- 用户 CRUD 操作
- JWT 认证
- 数据库迁移支持

### Changed
- 无

### Fixed
- 无

文档检查清单 ​

[ ] 所有导出的标识符都有注释
[ ] 注释以标识符名称开始
[ ] 注释简洁清晰，不冗余
[ ] 复杂函数包含示例
[ ] API 使用 Swagger 注释
[ ] README 包含安装和使用说明
[ ] CHANGELOG 记录重要变更
[ ] 文档与代码同步更新
[ ] 生成 Godoc 验证格式
[ ] Swagger 文档可正常访问