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"
  2. // Defines HTTP service
  3. service foo {
  4. get /ping
  5. }

Example 2. Write a login interface api file

  1. syntax = "v1"
  2. type (
  3. // Define the request body of the login interface
  4. LoginReq {
  5. Username string `json:"username"`
  6. Password string `json:"password"`
  7. }
  8. // Define the response body of the login interface
  9. LoginResp {
  10. Id int64 `json:"id"`
  11. Name string `json:"name"`
  12. Token string `json:"token"`
  13. ExpireAt string `json:"expireAt"`
  14. }
  15. )
  16. // Define an HTTP service
  17. // The name of the microservice is user, and the generated code directory and configuration file will be related to the value of user
  18. service user {
  19. // Define the name and method of the go file converted by http.HandleFunc
  20. @handler Login
  21. // define interface
  22. // The request method is post
  23. // route to /user/login
  24. // The request body is LoginReq
  25. // The response body is LoginResp, and the response body must be modified with the returns keyword
  26. post /user/login (LoginReq) returns (LoginResp)
  27. }

Example 3. Write a simple user service api file

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

Example 4. Write api services with intermediate

  1. syntax = "v1"
  2. type GetUserInfoReq {
  3. Id int64 `json:"id"`
  4. }
  5. type GetUserInfoResp {
  6. Id int64 `json:"id"`
  7. Name string `json:"name"`
  8. Desc string `json:"desc"`
  9. }
  10. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  11. // 1. Route grouping
  12. // 2. Middleware declaration
  13. // 3. Route prefix
  14. // 4. Timeout configuration
  15. // 5. jwt authentication switch
  16. // All declarations are only valid for routes in the current service
  17. @server (
  18. // 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
  19. middleware: AuthInterceptor
  20. )
  21. // Define a service named user
  22. service user {
  23. // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  24. @handler getUserInfo
  25. // define the interface
  26. // The request method is post
  27. // route to /user/info
  28. // The request body is GetUserInfoReq
  29. // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  30. post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  31. }

Example 5. Write api services with timeout configuration

  1. syntax = "v1"
  2. type GetUserInfoReq {
  3. Id int64 `json:"id"`
  4. }
  5. type GetUserInfoResp {
  6. Id int64 `json:"id"`
  7. Name string `json:"name"`
  8. Desc string `json:"desc"`
  9. }
  10. // The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
  11. // 1. Route grouping
  12. // 2. Middleware declaration
  13. // 3. Route prefix
  14. // 4. Timeout configuration
  15. // 5. jwt authentication switch
  16. // All declarations are only valid for routes in the current service
  17. @server (
  18. // 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
  19. // https://pkg.go.dev/time#Duration.String
  20. timeout: 3s
  21. )
  22. // Define a service named user
  23. service user {
  24. // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  25. @handler getUserInfo
  26. // define the interface
  27. // The request method is post
  28. // route to /user/info
  29. // The request body is GetUserInfoReq
  30. // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  31. post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  32. }

Example 6. Structure Reference

  1. syntax = "v1"
  2. type Base {
  3. Code int `json:"code"`
  4. Msg string `json:"msg"`
  5. }
  6. type UserInfo {
  7. Id int64 `json:"id"`
  8. Name string `json:"name"`
  9. Desc string `json:"desc"`
  10. }
  11. type GetUserInfoReq {
  12. Id int64 `json:"id"`
  13. }
  14. type GetUserInfoResp {
  15. // api supports nesting of anonymous structures, and also supports structure references
  16. Base
  17. Data UserInfo `json:"data"`
  18. }
  19. // Define a service named user
  20. service user {
  21. // Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
  22. @handler getUserInfo
  23. // define the interface
  24. // The request method is post
  25. // route to /user/info
  26. // The request body is GetUserInfoReq
  27. // The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
  28. post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
  29. }

Example 7. Control api service for max request body control

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

References