01 api模块

操作流程

创建文件夹与.api文件

创建api目录，执行命令 goctl api -o gobug.api

gobug.api 是文件名称，可根据自己需求进行自定义

编写 .api 文件

go-zero: 我们始终秉承工具大于约定和文档的理念，所以使用 api 模板进行最终文件的生成

info(
    title: "bug系统"
    desc: "基于go-zero的bug系统"
    author: "vogin"
    email: "654240315@qq.om"
    version: "1.0"
)
type UserRegisterReq {
    Username string `json:"username"`
    Realname string `json:"realname"`
    password string `json:"password"`
    Repassword string `json:"repassword"`
    Email string `json:"email"`
}
type UserRegisterResp {
    UserId string `json:"userId"`
    Username string `json:"username"`
    Realname string `json:"realname"`
    Email string `json:"email"`
}
type UserLoginReq {
    username string `form:"username"`
    password string `form:"password"`
}
type UserLoginResp {
    Id int64 `json:"id"`
    Username string `json:"username"`
    Realname string `json:"realname"`
    Email string `json:"email"`
    UserToken
}
type UserToken {
    Token string `json:"token"`
    RefreshToken string `json:"refresh_token"`
}
type (
    UserInfoResp {
        Id int64 `json:"id"`
        Username string `json:"username"`
        Realname string `json:"realname"`
        Email string `json:"email"`
    }
)
@server (
    group: passport
)
service passport_api {
    @handler UserRegister
    post /user/register(UserRegisterReq) returns (UserRegisterResp)
    @handler UserLogin
    post /user/login(UserLoginReq) returns (UserLoginResp)
}
@server(
    jwt: Auth
    group: user
    middleware: UserCheck
)
service user_api {
    @handler UserInfo
    get /user() returns (UserInfoResp)
}
@server(
    jwt: Auth
    middleware: UserCheck
)
service bug_api {
}

• service 定义api路由、参数以及返回值
  • @handler 决定文件名称
• server 一些注解内容
  • jwt: Auth 启动系统jwt验证规则
  • group：将handler统一放在哪个目录下，后面是目录名称
  • middleware：中间件名称

根据api生成数据模板内容

进入 api 文件夹，执行命令：

// goctl api go -api gobug.api -dir . // -> 此方式生成的文件规则默认风格比如 servicecontext.go 没有大小写区分或者下划线 
goctl api go -style="go_zero" -api gobug.api -dir .  // -> 此方式生成具有下划线风格的文件名，如 service_context.go

运行 api

go run bug_api.go -f etc/bug-api.yaml

注意事项

接收请求

参考文档：https://www.yuque.com/tal-tech/go-zero/ze9i30#fa570de9-2 https://github.com/tal-tech/zero-doc/blob/main/doc/mapping.md

后端根据不同的 Content-Type 接收前端传递的数据，那么api如何实现数据的接收。
是根据结构体中的tag不同，从而达到不同数据类型的接收。

application/json

type request {
    ping string `json:"ping"`
}

x-www-form-urlencoded

type request {
    ping string `form:"ping"`
}

数据验证

https://github.com/tal-tech/zero-doc/blob/main/doc/mapping.md

如何对前端传递的数据做自动验证

type (
    createUserReq struct {
        age    int8   `json:"age,default=20,range=(12:100]"` // 年龄
        name   string `json:"name"`                          // 名字
        alias  string `json:"alias,optional"`                // 别名
        sex    string `json:"sex,options=male|female"`       // 性别
        avatar string `json:"avatar,default=default.png"`    // 头像
    }
    createUserRes struct {
        success bool `json:"success"` // 是否成功
    }
)
service user {
    @doc(
        summary: 创建订单
    )
    @handler CreateUserHandler
    post /user/add(createUserReq) returns(createUserRes)
}

数据校验有很多种方式，包括以下但不限：

• age：默认不输入为20，输入则取值范围为(12:100]，前开后闭
• name：必填，不可为空
• alias：选填，可为空
• sex：必填，取值为male或female
• avatar：选填，默认为default.png

更多参考 unmarshaler_test