01API语法与路由配置详解

go-zero API语法与路由配置详解

1. API定义文件规范

// api/user.api
syntax = "v1"

type LoginReq {
    Username string `json:"username"`
    Password string `json:"password"`
}

type Response {
    Code int    `json:"code"`
    Data string `json:"data"`
}

service user {
    @handler Login
    post /api/v1/login (LoginReq) returns (Response)
}

2. 路由注册机制

# 使用goctl生成路由代码
goctl api go -api user.api -dir .

3. 参数校验语法

// 带验证的请求结构
type RegisterReq {
    Username string `json:"username" validate:"required,min=6"`
    Email    string `json:"email" validate:"email"`
    Password string `json:"password" validate:"required,contains=!@#"`
}

4. 与Gin框架对比

特性	go-zero	Gin
路由定义方式	API描述文件声明式配置	代码内链式配置
参数校验	自动生成校验代码	手动编写校验逻辑
代码生成	内置goctl生成完整项目结构	需自行组织架构
性能表现	内置优化路由树	标准实现

5. 最佳实践

1. 使用API文件统一管理接口规范
2. 通过goctl自动生成路由、handler和校验代码
3. 采用分层校验：基础校验在API文件，业务校验在logic层
4. 合理使用路由分组（通过service定义实现）