api 语法

概述

api 是 go-zero 自研的领域特性语言（下文称 api 语言 或 api 描述语言），旨在实现人性化的基础描述语言，作为生成 HTTP 服务最基本的描述语言。

api 领域特性语言包含语法版本，info 块，结构体声明，服务描述等几大块语法组成，其中结构体和 Golang 结构体 语法几乎一样，只是移出了 struct 关键字。

快速入门

本次仅以 demo 形式快速介绍 api 文件的写法，更详细的写法示例可参考 《API 定义完整示例》，详细 api 语法规范可参考 《API 规范》。

示例 1. 编写最简单的 ping 路由服务

  1. syntax = "v1"
  3. // 定义 HTTP 服务
  4. service foo {
  5.     get /ping
  6. }

示例 2. 编写一个登录接口 api 文件

  1. syntax = "v1"
  3. type (
  4.     // 定义登录接口的请求体
  5.     LoginReq {
  6.         Username string `json:"username"`
  7.         Password string `json:"password"`
  8.     }
  9.     // 定义登录接口的响应体
  10.     LoginResp {
  11.         Id       int64  `json:"id"`
  12.         Name     string `json:"name"`
  13.         Token    string `json:"token"`
  14.         ExpireAt string `json:"expireAt"`
  15.     }
  16. )
  18. // 定义 HTTP 服务
  19. // 微服务名称为 user，生成的代码目录和配置文件将和 user 值相关
  20. service user {
  21.     // 定义 http.HandleFunc 转换的 go 文件名称及方法
  22.     @handler Login
  23.     // 定义接口
  24.     // 请求方法为 post
  25.     // 路由为 /user/login
  26.     // 请求体为 LoginReq
  27.     // 响应体为 LoginResp，响应体必须有 returns 关键字修饰
  28.     post /user/login (LoginReq) returns (LoginResp)
  29. }

示例 3. 编写简单的用户服务 api 文件

  1. syntax = "v1"
  3. type (
  4.     // 定义登录接口的 json 请求体
  5.     LoginReq {
  6.         Username string `json:"username"`
  7.         Password string `json:"password"`
  8.     }
  9.     // 定义登录接口的 json 响应体
  10.     LoginResp {
  11.         Id       int64  `json:"id"`
  12.         Name     string `json:"name"`
  13.         Token    string `json:"token"`
  14.         ExpireAt string `json:"expireAt"`
  15.     }
  16. )
  18. type (
  19.     // 定义获取用户信息的 json 请求体
  20.     GetUserInfoReq {
  21.         Id int64 `json:"id"`
  22.     }
  23.     // 定义获取用户信息的 json 响应体
  24.     GetUserInfoResp {
  25.         Id   int64  `json:"id"`
  26.         Name string `json:"name"`
  27.         Desc string `json:"desc"`
  28.     }
  29.     // 定义更新用户信息的 json 请求体
  30.     UpdateUserInfoReq {
  31.         Id   int64  `json:"id"`
  32.         Name string `json:"name"`
  33.         Desc string `json:"desc"`
  34.     }
  35. )
  37. // 定义 HTTP 服务
  38. // @server 语法块主要用于控制对 HTTP 服务生成时 meta 信息，目前支持功能有：
  39. // 1. 路由分组
  40. // 2. 中间件声明
  41. // 3. 路由前缀
  42. // 4. 超时配置
  43. // 5. jwt 鉴权开关
  44. // 所有声明仅对当前 service 中的路由有效
  45. @server (
  46.     // 代表当前 service 代码块下的路由生成代码时都会被放到 login 目录下
  47.     group: login
  48.     // 定义路由前缀为 "/v1"
  49.     prefix: /v1
  50. )
  51. // 微服务名称为 user，生成的代码目录和配置文件将和 user 值相关
  52. service user {
  53.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  54.     @handler login
  55.     // 定义接口
  56.     // 请求方法为 post
  57.     // 路由为 /user/login
  58.     // 请求体为 LoginReq
  59.     // 响应体为 LoginResp，响应体必须有 returns 关键字修饰
  60.     post /user/login (LoginReq) returns (LoginResp)
  61. }
  63. // @server 语法块主要用于控制对 HTTP 服务生成时 meta 信息，目前支持功能有：
  64. // 1. 路由分组
  65. // 2. 中间件声明
  66. // 3. 路由前缀
  67. // 4. 超时配置
  68. // 5. jwt 鉴权开关
  69. // 所有声明仅对当前 service 中的路由有效
  70. @server (
  71.     // 代表当前 service 代码块下的所有路由均需要 jwt 鉴权
  72.     // goctl 生成代码时会将当前 service 代码块下的接口
  73.     // 信息添加上 jwt 相关代码，Auth 值为 jwt 密钥，过期
  74.     // 等信息配置的 golang 结构体名称
  75.     jwt: Auth
  76.     // 代表当前 service 代码块下的路由生成代码时都会被放到 user 目录下
  77.     group: user
  78.     // 定义路由前缀为 "/v1"
  79.     prefix: /v1
  80. )
  81. // 注意，定义多个 service 代码块时，服务名称必须一致，因此这里的服务名称必须
  82. // 和上文的 service 名称一样，为 user 服务。
  83. service user {
  84.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  85.     @handler getUserInfo
  86.     // 定义接口
  87.     // 请求方法为 post
  88.     // 路由为 /user/info
  89.     // 请求体为 GetUserInfoReq
  90.     // 响应体为 GetUserInfoResp，响应体必须有 returns 关键字修饰
  91.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  93.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  94.     @handler updateUserInfo
  95.     // 定义接口
  96.     // 请求方法为 post
  97.     // 路由为 /user/info/update
  98.     // 请求体为 UpdateUserInfoReq
  99.     // 由于不需要响应体，因此可以忽略不写
  100.     post /user/info/update (UpdateUserInfoReq)
  101. }

示例 4. 编写带有中间件的 api 服务

  1. syntax = "v1"
  3. type GetUserInfoReq {
  4.     Id int64 `json:"id"`
  5. }
  7. type GetUserInfoResp {
  8.     Id   int64  `json:"id"`
  9.     Name string `json:"name"`
  10.     Desc string `json:"desc"`
  11. }
  13. // @server 语法块主要用于控制对 HTTP 服务生成时 meta 信息，目前支持功能有：
  14. // 1. 路由分组
  15. // 2. 中间件声明
  16. // 3. 路由前缀
  17. // 4. 超时配置
  18. // 5. jwt 鉴权开关
  19. // 所有声明仅对当前 service 中的路由有效
  20. @server (
  21.     // 定义一个鉴权控制的中间件，多个中间件以英文逗号,分割，如 Middleware1,Middleware2,中间件按声明顺序执行
  22.     middleware: AuthInterceptor
  23. )
  24. // 定义一个名称为 user 的服务
  25. service user {
  26.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  27.     @handler getUserInfo
  28.     // 定义接口
  29.     // 请求方法为 post
  30.     // 路由为 /user/info
  31.     // 请求体为 GetUserInfoReq
  32.     // 响应体为 GetUserInfoResp，响应体必须有 returns 关键字修饰
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

示例 5. 编写带有超时配置的 api 服务

  1. syntax = "v1"
  3. type GetUserInfoReq {
  4.     Id int64 `json:"id"`
  5. }
  7. type GetUserInfoResp {
  8.     Id   int64  `json:"id"`
  9.     Name string `json:"name"`
  10.     Desc string `json:"desc"`
  11. }
  13. // @server 语法块主要用于控制对 HTTP 服务生成时 meta 信息，目前支持功能有：
  14. // 1. 路由分组
  15. // 2. 中间件声明
  16. // 3. 路由前缀
  17. // 4. 超时配置
  18. // 5. jwt 鉴权开关
  19. // 所有声明仅对当前 service 中的路由有效
  20. @server (
  21.     // 定义一个超时时长为 3 秒的超时配置，这里可填写为 time.Duration 的字符串形式，详情可参考 
  22.     // https://pkg.go.dev/time#Duration.String
  23.     timeout: 3s
  24. )
  25. // 定义一个名称为 user 的服务
  26. service user {
  27.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  28.     @handler getUserInfo
  29.     // 定义接口
  30.     // 请求方法为 post
  31.     // 路由为 /user/info
  32.     // 请求体为 GetUserInfoReq
  33.     // 响应体为 GetUserInfoResp，响应体必须有 returns 关键字修饰
  34.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  35. }

示例 6. 结构体引用

  1. syntax = "v1"
  3. type Base {
  4.     Code int    `json:"code"`
  5.     Msg  string `json:"msg"`
  6. }
  8. type UserInfo {
  9.     Id   int64  `json:"id"`
  10.     Name string `json:"name"`
  11.     Desc string `json:"desc"`
  12. }
  14. type GetUserInfoReq {
  15.     Id int64 `json:"id"`
  16. }
  18. type GetUserInfoResp {
  19.     // api 支持匿名结构体嵌套，也支持结构体引用
  20.     Base
  21.     Data UserInfo `json:"data"`
  22. }
  24. // 定义一个名称为 user 的服务
  25. service user {
  26.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  27.     @handler getUserInfo
  28.     // 定义接口
  29.     // 请求方法为 post
  30.     // 路由为 /user/info
  31.     // 请求体为 GetUserInfoReq
  32.     // 响应体为 GetUserInfoResp，响应体必须有 returns 关键字修饰
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

示例 7. 控制最大请求体控制的 api 服务

  1. syntax = "v1"
  3. type GetUserInfoReq {
  4.     Id int64 `json:"id"`
  5. }
  7. type GetUserInfoResp {
  8.     Id   int64  `json:"id"`
  9.     Name string `json:"name"`
  10.     Desc string `json:"desc"`
  11. }
  13. // @server 语法块主要用于控制对 HTTP 服务生成时 meta 信息，目前支持功能有：
  14. // 1. 路由分组
  15. // 2. 中间件声明
  16. // 3. 路由前缀
  17. // 4. 超时配置
  18. // 5. jwt 鉴权开关
  19. // 所有声明仅对当前 service 中的路由有效
  20. @server (
  21.     // 定义一个请求体限制在 1MB 以内的请求，goctl >= 1.5.0 版本支持
  22.     maxBytes: 1048576
  23. )
  24. // 定义一个名称为 user 的服务
  25. service user {
  26.     // 定义 http.HandleFunc 转换的 go 文件名称及方法，每个接口都会跟一个 handler
  27.     @handler getUserInfo
  28.     // 定义接口
  29.     // 请求方法为 post
  30.     // 路由为 /user/info
  31.     // 请求体为 GetUserInfoReq
  32.     // 响应体为 GetUserInfoResp，响应体必须有 returns 关键字修饰
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

参考文献