api syntax

Overview

api is the domain characteristic language of go-zero (below is api language or api description), which is intended to humanize as the most basic description language for generating HTTP services.

The api field feature language contains syntax versions, info blocks, structural statements, service descriptions, etc., where the structure is almost the same as the Golang structural syntax, but only the structure keywords.

Getting started

This is a quick introduction to api file writing only in demo form. More detailed examples can be found in Full Example of API Definitions, detailed api syntax norms can be referenced API norms.

Example 1. Write the easiest ping routing service

  1. syntax = "v1"
  3. // Defines HTTP service
  4. service foo {
  5.     get /ping
  6. }

Example 2. Write a login interface api file

  1. syntax = "v1"
  3. type (
  4.     // Define the request body of the login interface
  5.     LoginReq {
  6.         Username string `json:"username"`
  7.         Password string `json:"password"`
  8.     }
  9.     // Define the response body of the login interface
  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. // Define an HTTP service
  19. // The name of the microservice is user, and the generated code directory and configuration file will be related to the value of user
  20. service user {
  21.     // Define the name and method of the go file converted by http.HandleFunc
  22.     @handler Login
  23.     // define interface
  24.     // The request method is post
  25.     // route to /user/login
  26.     // The request body is LoginReq
  27.     // The response body is LoginResp, and the response body must be modified with the returns keyword
  28.     post /user/login (LoginReq) returns (LoginResp)
  29. }

Example 3. Write a simple user service api file

  1. syntax = "v1"
  3. type (
  4.     // Define the json request body of the login interface
  5.     LoginReq {
  6.         Username string `json:"username"`
  7.         Password string `json:"password"`
  8.     }
  9.     // Define the json response body of the login interface
  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.     // Define the json request body for obtaining user information
  20.     GetUserInfoReq {
  21.         Id int64 `json:"id"`
  22.     }
  23.     // Define the json response body for getting user information
  24.     GetUserInfoResp {
  25.         Id   int64  `json:"id"`
  26.         Name string `json:"name"`
  27.         Desc string `json:"desc"`
  28.     }
  29.     // Define the json request body for updating user information
  30.     UpdateUserInfoReq {
  31.         Id   int64  `json:"id"`
  32.         Name string `json:"name"`
  33.         Desc string `json:"desc"`
  34.     }
  35. )
  37. // define HTTP service
  38. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  39. // 1. Route grouping
  40. // 2. Middleware declaration
  41. // 3. Route prefix
  42. // 4. Timeout configuration
  43. // 5. jwt authentication switch
  44. // All declarations are only valid for routes in the current service
  45. @server (
  46.     // Represents the routes under the current service code block will be placed in the login directory when generating code
  47.     group: login
  48.     // Define route prefix as "/v1"
  49.     prefix: /v1
  50. )
  51. // The name of the microservice is user, and the generated code directory and configuration file will be related to the value of user
  52. service user {
  53.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  54.     @handler login
  55.     // define the interface
  56.     // The request method is post
  57.     // route to /user/login
  58.     // The request body is LoginReq
  59.     // The response body is LoginResp, and the response body must be modified with the returns keyword
  60.     post /user/login (LoginReq) returns (LoginResp)
  61. }
  63. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  64. // 1. Route grouping
  65. // 2. Middleware declaration
  66. // 3. Route prefix
  67. // 4. Timeout configuration
  68. // 5. jwt authentication switch
  69. // All declarations are only valid for routes in the current service
  70. @server (
  71.     // Represents that all routes under the current service code block require jwt authentication
  72.     // When goctl generates code, the interface under the current service code block will be
  73.     // Add jwt related codes to the information, the Auth value is the jwt key, expired
  74.     // The name of the golang structure configured with other information
  75.     jwt: Auth
  76.     // Represents the routes under the current service code block will be placed in the user directory when generating code
  77.     group: user
  78.     // Define route prefix as "/v1"
  79.     prefix: /v1
  80. )
  81. // Note that when defining multiple service code blocks, the service names must be consistent, so the service names here must
  82. // Same as the service name above, serving user.
  83. service user {
  84.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  85.     @handler getUserInfo
  86.     // define the interface
  87.     // The request method is post
  88.     // route to /user/info
  89.     // The request body is GetUserInfoReq
  90.     // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  91.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  93.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  94.     @handler updateUserInfo
  95.     // define the interface
  96.     // The request method is post
  97.     // route to /user/info/update
  98.     // The request body is UpdateUserInfoReq
  99.     // Since the response body is not required, it can be ignored
  100.     post /user/info/update (UpdateUserInfoReq)
  101. }

Example 4. Write api services with intermediate

  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. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  14. // 1. Route grouping
  15. // 2. Middleware declaration
  16. // 3. Route prefix
  17. // 4. Timeout configuration
  18. // 5. jwt authentication switch
  19. // All declarations are only valid for routes in the current service
  20. @server (
  21.     // Define a middleware for authentication control. Multiple middleware are separated by English commas, such as Middleware1, Middleware2, and middleware are executed in the order of declaration
  22.     middleware: AuthInterceptor
  23. )
  24. // Define a service named user
  25. service user {
  26.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  27.     @handler getUserInfo
  28.     // define the interface
  29.     // The request method is post
  30.     // route to /user/info
  31.     // The request body is GetUserInfoReq
  32.     // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

Example 5. Write api services with timeout configuration

  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. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  14. // 1. Route grouping
  15. // 2. Middleware declaration
  16. // 3. Route prefix
  17. // 4. Timeout configuration
  18. // 5. jwt authentication switch
  19. // All declarations are only valid for routes in the current service
  20. @server (
  21.     // Define a timeout configuration with a timeout duration of 3 seconds, which can be filled in as a string form of time.Duration here, for details, please refer to
  22.     // https://pkg.go.dev/time#Duration.String
  23.     timeout: 3s
  24. )
  25. // Define a service named user
  26. service user {
  27.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  28.     @handler getUserInfo
  29.     // define the interface
  30.     // The request method is post
  31.     // route to /user/info
  32.     // The request body is GetUserInfoReq
  33.     // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  34.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  35. }

Example 6. Structure Reference

  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 supports nesting of anonymous structures, and also supports structure references
  20.     Base
  21.     Data UserInfo `json:"data"`
  22. }
  24. // Define a service named user
  25. service user {
  26.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  27.     @handler getUserInfo
  28.     // define the interface
  29.     // The request method is post
  30.     // route to /user/info
  31.     // The request body is GetUserInfoReq
  32.     // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

Example 7. Control api service for max request body control

  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. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  14. // 1. Route grouping
  15. // 2. Middleware declaration
  16. // 3. Route prefix
  17. // 4. Timeout configuration
  18. // 5. jwt authentication switch
  19. // All declarations are only valid for routes in the current service
  20. @server (
  21.     // Define a request with a request body limited to 1MB, supported by goctl >= 1.5.0
  22.     maxBytes: 1024
  23. )
  24. // Define a service named user
  25. service user {
  26.     // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  27.     @handler getUserInfo
  28.     // define the interface
  29.     // The request method is post
  30.     // route to /user/info
  31.     // The request body is GetUserInfoReq
  32.     // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  33.     post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  34. }

References