掌握API建模：基本概念和實踐
對于Go語言開發者來說，Go-Zero的API語法學習和理解成本極低，我們可以很輕松的學會API語法。下面我會為大家介紹重點需要掌握的語法。更詳細的語法規范，可以參考官網：API 規范 | go-zero Documentation[4]
cd demo
goctl api go -api demo.api -dir . -style gozero 基礎的API文件
golang中的預定義類型、常量、函數，以及關鍵字在api里面同樣適用
//預定義類型:
any bool byte comparable
complex64 complex128 error float32 float64
int int8 int16 int32 int64 rune string
uint uint8 uint16 uint32 uint64 uintptr
//預定義常量:
true false iota
//零值:
nil
//預定義函數:
append cap close complex copy delete imag len
make new panic print println real recover 關鍵字
break default func interface select
case defer go map struct
chan else goto package switch
const fallthrough if range type
continue for import return var tip:需要注意的是 goctl api不支持any類型！！！
type 開頭struct關鍵字type StructureExample {
// 基本數據類型示例
BaseInt int json:"base_int"
BaseBool bool json:"base_bool"
BaseString string json:"base_string"
BaseByte byte json:"base_byte"
BaseFloat32 float32 json:"base_float32"
BaseFloat64 float64 json:"base_float64"
// 切片示例
BaseIntSlice []int json:"base_int_slice"
BaseBoolSlice []bool json:"base_bool_slice"
BaseStringSlice []string json:"base_string_slice"
BaseByteSlice []byte json:"base_byte_slice"
BaseFloat32Slice []float32 json:"base_float32_slice"
BaseFloat64Slice []float64 json:"base_float64_slice"
// map 示例
BaseMapIntString map[int]string json:"base_map_int_string"
BaseMapStringInt map[string]int json:"base_map_string_int"
BaseMapStringStruct map[string]*StructureExample json:"base_map_string_struct"
BaseMapStringIntArray map[string][]int json:"base_map_string_int_array"
// 匿名示例
*Base
// 指針示例
Base4 *Base json:"base4"
// 新的特性（ goctl >= 1.5.1 版本支持 ）
// 標簽忽略示例
TagOmit string
} 我們可以通過prefix關鍵字區分路由組
接著再使用goctl api生成代碼以及swagger，將swagger導入apifox查看路由前綴，可以看見就增添了前綴/demo。
不知道怎么生成api代碼的同學可以看我往期的gozero實戰分享——go-zero goctl實戰[5]
當我們的業務體量上來后，服務接口也會越來越多，生成的代碼文件（handler、logic文件等）也會越來越多。這時候我們就需要對不同的接口按一定的分組進行區分，用文件夾進行隔離，以便于開發和維護。
在config文件中添加一個JWT認證需要的密鑰和過期時間配置
JwtAuth struct { // JWT 認證需要的密鑰和過期時間配置
AccessSecret string
AccessExpire int64
} 
使用方法也很簡單，我們在@service語句塊中添加jwt關鍵字，使用Auth即可開啟jwt。
通過測試請求我們可以看見返回401沒有權限，說明jwt校驗生效了
/ 開頭 2. 路由節點必須以 / 分隔:，但是 : 必須是路由節點的第一個字符，: 后面的節點值必須要在結請求體中有 path tag 聲明，用于接收路由參數，詳細規則可參考 路由參數[6]。4. 路由節點可以包含字母、數字(goctl 1.5.1 支持，可參考 新版 API 解析器使用[7])、下劃線、中劃線接收規則說明生效范圍示例jsonjson 序列化請求體&響應體json:"foo"path路由參數請求體path:"id"formpost 請求的表單(支持 content-type 為?form-data?和?x-www-form-urlencoded) 參數請求接收標識，get 請求的 query 參數接收標識請求體form:"name"headerhttp 請求體接收標識請求體header:"Content-Length" |
|---|
在svc包的servicecontext.go中注冊中間件
生成的中間件代碼如下
syntax = "v1" 
syntax = "v1"
type Request {
Name string path:"name,options=you|me"
}
type Response {
Message string json:"message"
}
@server (
prefix :/demo
group: demo_api
jwt: JwtAuth
middleware: Demo_middleware
)
// 分組1的服務
service demo-api {
@handler DemoHandler
post /from (Request) returns (Response)
}
// 分組2的服務
@server (
prefix :/demo1
group: demo_api1
)
service demo-api {
@handler DemoHandler1
get /from/:name(Request) returns (Response)
} 這篇文章詳細介紹了如何使用Go-Zero進行API的定義，并進行了實際演示。希望對你有幫助。
本文章轉載微信公眾號@王中陽
