📋 第18课：RESTful API

• 掌握RESTful设计原则
• 实现CRUD API
• 理解HTTP方法语义
• 掌握状态码规范

✅ 验证通过 — 实机运行结果：

GET /api/users
{
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "zhang@example.com"
    },
    {
      "id": 2,
      "name": "李四",
      "email": "li@example.com"
    },
    {
      "id": 3,
      "name": "王五",
      "email": "wang@example.com"
    }
  ],
  "method": "GET",
  "path": "/api/users",
  "status": 200,
  "time": "2026-05-19T16:35:27+08:00"
}

GET /api/users/2
{
  "error": "Not found",
  "method": "GET",
  "path": "/api/users/2",
  "status": 404,
  "time": "2026-05-19T16:35:27+08:00"
}

POST /api/users
{
  "data": {
    "id": 4,
    "name": "赵六",
    "email": "zhao@ex.com"
  },
  "method": "POST",
  "path": "/api/users",
  "status": 201,
  "time": "2026-05-19T16:35:27+08:00"
}

=== REST原则 ===
GET=查询 POST=创建 PUT=更新 DELETE=删除
200=OK 201=Created 400=Bad 404=NotFound 500=Error

1. 资源用名词复数
2. HTTP动词表操作
3. 正确状态码
4. 版本化API
5. 分页+过滤

• Go官方文档 — 深入理解本课主题
• Effective Go — Go最佳实践
• Go Blog — 官方博客设计决策解读
• Go by Example — 实例学习

1. 动手编写代码，不要只看不练
2. 使用go doc查看标准库文档
3. 编写测试用例验证理解
4. 阅读优秀开源项目的源码
5. 在项目中应用所学知识

// 1. 预分配切片容量
s := make([]int, 0, expectedSize)

// 2. 使用strings.Builder拼接
var b strings.Builder
b.WriteString("hello")

// 3. 对象池复用
var bufPool = sync.Pool{New: func() interface{} { return new(bytes.Buffer) }}

// 4. 减少逃逸分析
// 小对象栈分配，大对象堆分配

// 5. benchmark测试
func BenchmarkXxx(b *testing.B) {
    for i := 0; i < b.N; i++ { ... }
}

// 1. fmt.Printf格式化
fmt.Printf("%+v
", struct)  // 带字段名
fmt.Printf("%#v
", value)   // Go语法

// 2. log包
log.Printf("debug: value=%v", val)

// 3. delve调试器
// dlv debug ./main.go

// 4. pprof性能分析
import _ "net/http/pprof"
go http.ListenAndServe(":6060", nil)

• Go官方文档 — go.dev/doc 最权威的参考
• Effective Go — go.dev/doc/effective_go 最佳实践指南
• Go Blog — go.dev/blog 设计决策深度解读
• Go by Example — gobyexample.com 实例驱动学习
• Go语言中文网 — 中文社区与教程

1. 动手编码 — 只看不练等于没学，每课代码必须自己敲一遍
2. 使用go doc — go doc fmt.Printf 查看标准库文档
3. 编写测试 — go test 验证你的理解是否正确
4. 阅读源码 — 标准库是Go最佳实践的活教材
5. 项目实战 — 在真实项目中应用所学

// 1. 预分配切片容量 — 避免频繁扩容
s := make([]int, 0, expectedSize)

// 2. strings.Builder拼接 — 比fmt.Sprintf快3-5倍
var b strings.Builder
b.WriteString("hello")
b.WriteString(" world")
result := b.String()

// 3. sync.Pool对象复用 — 减少GC压力
var bufPool = sync.Pool{
    New: func() interface{} { return new(bytes.Buffer) },
}
buf := bufPool.Get().(*bytes.Buffer)
defer bufPool.Put(buf)

// 4. 减少堆分配 — 小对象栈分配，避免逃逸
// 用 go build -gcflags="-m" 分析逃逸

// 5. 使用benchmark验证性能
func BenchmarkXxx(b *testing.B) {
    for i := 0; i < b.N; i++ {
        // 被测代码
    }
}
// go test -bench=. -benchmem

// 1. 格式化调试输出
fmt.Printf("%+v
", myStruct)  // 带字段名
fmt.Printf("%#v
", myValue)   // Go语法表示

// 2. log包运行时日志
log.Printf("[DEBUG] value=%v", val)
log.SetFlags(log.LstdFlags | log.Lshortfile)

// 3. delve源码调试器
// 安装: go install github.com/go-delve/delve/cmd/dlv@latest
// 使用: dlv debug ./main.go
// 命令: break main.main / continue / next / print

// 4. pprof性能分析
import _ "net/http/pprof"
go http.ListenAndServe(":6060", nil)
// 访问: http://localhost:6060/debug/pprof/
// 命令: go tool pprof http://localhost:6060/debug/pprof/profile

// 5. race detector竞态检测
// go run -race main.go
// go test -race ./...

myproject/
├── cmd/                    # 可执行程序入口
│   └── server/
│       └── main.go
├── internal/               # 私有代码(不可外部导入)
│   ├── handler/            # HTTP处理
│   ├── service/            # 业务逻辑
│   ├── repository/         # 数据访问
│   └── model/              # 数据模型
├── pkg/                    # 可复用公共包
│   └── utils/
├── api/                    # API定义(proto/openapi)
├── configs/                # 配置文件
├── scripts/                # 构建/部署脚本
├── test/                   # 集成测试
├── go.mod
├── go.sum
├── Makefile
└── Dockerfile

// 命名规范
// 包名: 小写单词, 不用下划线  package httputil
// 导出: 大写开头              func CreateUser()
// 未导出: 小写开头            func validateInput()
// 接口: -er后缀              type Reader interface{}
// 常量: 驼峰                 const maxRetries = 3
// 枚举: 类型+常量            type Role int; const Admin Role = 0

// 错误处理规范
// 错误变量: Err前缀           var ErrNotFound = errors.New("...")
// 错误类型: Error后缀         type ValidationError struct{...}
// 包装: %w                    fmt.Errorf("查询失败: %w", err)

// 注释规范
// 导出符号必须有注释
// 注释以符号名开头            // CreateUser creates a new user.
// 包注释: doc.go              // Package user handles user operations.