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
syntax = "v1"
// Defines HTTP service
service foo {
get /ping
}
Example 2. Write a login interface api file
syntax = "v1"
type (
// Define the request body of the login interface
LoginReq {
Username string `json:"username"`
Password string `json:"password"`
}
// Define the response body of the login interface
LoginResp {
Id int64 `json:"id"`
Name string `json:"name"`
Token string `json:"token"`
ExpireAt string `json:"expireAt"`
}
)
// Define an HTTP service
// The name of the microservice is user, and the generated code directory and configuration file will be related to the value of user
service user {
// Define the name and method of the go file converted by http.HandleFunc
@handler Login
// define interface
// The request method is post
// route to /user/login
// The request body is LoginReq
// The response body is LoginResp, and the response body must be modified with the returns keyword
post /user/login (LoginReq) returns (LoginResp)
}
Example 3. Write a simple user service api file
syntax = "v1"
type (
// Define the json request body of the login interface
LoginReq {
Username string `json:"username"`
Password string `json:"password"`
}
// Define the json response body of the login interface
LoginResp {
Id int64 `json:"id"`
Name string `json:"name"`
Token string `json:"token"`
ExpireAt string `json:"expireAt"`
}
)
type (
// Define the json request body for obtaining user information
GetUserInfoReq {
Id int64 `json:"id"`
}
// Define the json response body for getting user information
GetUserInfoResp {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
// Define the json request body for updating user information
UpdateUserInfoReq {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
)
// define HTTP service
// The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
// 1. Route grouping
// 2. Middleware declaration
// 3. Route prefix
// 4. Timeout configuration
// 5. jwt authentication switch
// All declarations are only valid for routes in the current service
@server (
// Represents the routes under the current service code block will be placed in the login directory when generating code
group: login
// Define route prefix as "/v1"
prefix: /v1
)
// The name of the microservice is user, and the generated code directory and configuration file will be related to the value of user
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler login
// define the interface
// The request method is post
// route to /user/login
// The request body is LoginReq
// The response body is LoginResp, and the response body must be modified with the returns keyword
post /user/login (LoginReq) returns (LoginResp)
}
// The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
// 1. Route grouping
// 2. Middleware declaration
// 3. Route prefix
// 4. Timeout configuration
// 5. jwt authentication switch
// All declarations are only valid for routes in the current service
@server (
// Represents that all routes under the current service code block require jwt authentication
// When goctl generates code, the interface under the current service code block will be
// Add jwt related codes to the information, the Auth value is the jwt key, expired
// The name of the golang structure configured with other information
jwt: Auth
// Represents the routes under the current service code block will be placed in the user directory when generating code
group: user
// Define route prefix as "/v1"
prefix: /v1
)
// Note that when defining multiple service code blocks, the service names must be consistent, so the service names here must
// Same as the service name above, serving user.
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler getUserInfo
// define the interface
// The request method is post
// route to /user/info
// The request body is GetUserInfoReq
// The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler updateUserInfo
// define the interface
// The request method is post
// route to /user/info/update
// The request body is UpdateUserInfoReq
// Since the response body is not required, it can be ignored
post /user/info/update (UpdateUserInfoReq)
}
Example 4. Write api services with intermediate
syntax = "v1"
type GetUserInfoReq {
Id int64 `json:"id"`
}
type GetUserInfoResp {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
// The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
// 1. Route grouping
// 2. Middleware declaration
// 3. Route prefix
// 4. Timeout configuration
// 5. jwt authentication switch
// All declarations are only valid for routes in the current service
@server (
// 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
middleware: AuthInterceptor
)
// Define a service named user
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler getUserInfo
// define the interface
// The request method is post
// route to /user/info
// The request body is GetUserInfoReq
// The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
}
Example 5. Write api services with timeout configuration
syntax = "v1"
type GetUserInfoReq {
Id int64 `json:"id"`
}
type GetUserInfoResp {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
// The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
// 1. Route grouping
// 2. Middleware declaration
// 3. Route prefix
// 4. Timeout configuration
// 5. jwt authentication switch
// All declarations are only valid for routes in the current service
@server (
// 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
// https://pkg.go.dev/time#Duration.String
timeout: 3s
)
// Define a service named user
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler getUserInfo
// define the interface
// The request method is post
// route to /user/info
// The request body is GetUserInfoReq
// The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
}
Example 6. Structure Reference
syntax = "v1"
type Base {
Code int `json:"code"`
Msg string `json:"msg"`
}
type UserInfo {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
type GetUserInfoReq {
Id int64 `json:"id"`
}
type GetUserInfoResp {
// api supports nesting of anonymous structures, and also supports structure references
Base
Data UserInfo `json:"data"`
}
// Define a service named user
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler getUserInfo
// define the interface
// The request method is post
// route to /user/info
// The request body is GetUserInfoReq
// The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
}
Example 7. Control api service for max request body control
syntax = "v1"
type GetUserInfoReq {
Id int64 `json:"id"`
}
type GetUserInfoResp {
Id int64 `json:"id"`
Name string `json:"name"`
Desc string `json:"desc"`
}
// The @server syntax block is mainly used to control the meta information when generating HTTP services. Currently, the supported functions are:
// 1. Route grouping
// 2. Middleware declaration
// 3. Route prefix
// 4. Timeout configuration
// 5. jwt authentication switch
// All declarations are only valid for routes in the current service
@server (
// Define a request with a request body limited to 1MB, supported by goctl >= 1.5.0
maxBytes: 1048576
)
// Define a service named user
service user {
// Define the name and method of the go file converted by http.HandleFunc, each interface will be followed by a handler
@handler getUserInfo
// define the interface
// The request method is post
// route to /user/info
// The request body is GetUserInfoReq
// The response body is GetUserInfoResp, the response body must be decorated with the returns keyword
post /user/info (GetUserInfoReq) returns (GetUserInfoResp)
}