久久久久久极精品久久久,久久久久大香线焦,亚洲一区二区三区中文字幕

學(xué)習(xí)API語(yǔ)法

對(duì)于Go語(yǔ)言開(kāi)發(fā)者來(lái)說(shuō)，Go-Zero的API語(yǔ)法學(xué)習(xí)和理解成本極低，我們可以很輕松的學(xué)會(huì)API語(yǔ)法。下面我會(huì)為大家介紹重點(diǎn)需要掌握的語(yǔ)法。更詳細(xì)的語(yǔ)法規(guī)范，可以參考官網(wǎng)：API 規(guī)范 | go-zero Documentation^[4]

生成API文件

cd demo  

goctl api go -api demo.api -dir . -style gozero

基礎(chǔ)的API文件

ID標(biāo)識(shí)符

golang中的預(yù)定義類(lèi)型、常量、函數(shù)，以及關(guān)鍵字在api里面同樣適用

預(yù)定義

//預(yù)定義類(lèi)型:  

    any bool byte comparable  

    complex64 complex128 error float32 float64  

    int int8 int16 int32 int64 rune string  

    uint uint8 uint16 uint32 uint64 uintptr  



//預(yù)定義常量:  

    true false iota  



//零值:  

    nil  



//預(yù)定義函數(shù):  

    append cap close complex copy delete imag len  

    make new panic print println real recover

關(guān)鍵字

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類(lèi)型！！！

類(lèi)型聲明

規(guī)則

類(lèi)型聲明必須以 type 開(kāi)頭
不需要聲明 struct關(guān)鍵字
不支持嵌套結(jié)構(gòu)體聲明
不支持別名

示例

type StructureExample {  

    // 基本數(shù)據(jù)類(lèi)型示例  

    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 版本支持 ）  
    // 標(biāo)簽忽略示例  
    TagOmit string  
}

路由前綴

我們可以通過(guò)prefix關(guān)鍵字區(qū)分路由組

接著再使用goctl api生成代碼以及swagger，將swagger導(dǎo)入apifox查看路由前綴，可以看見(jiàn)就增添了前綴/demo。

不知道怎么生成api代碼的同學(xué)可以看我往期的gozero實(shí)戰(zhàn)分享——go-zero goctl實(shí)戰(zhàn)^[5]

服務(wù)分組

當(dāng)我們的業(yè)務(wù)體量上來(lái)后，服務(wù)接口也會(huì)越來(lái)越多，生成的代碼文件（handler、logic文件等）也會(huì)越來(lái)越多。這時(shí)候我們就需要對(duì)不同的接口按一定的分組進(jìn)行區(qū)分，用文件夾進(jìn)行隔離，以便于開(kāi)發(fā)和維護(hù)。

分組前的目錄結(jié)構(gòu)是這樣的

我們先將生成的handler和logic文件刪除。
只需要在@server語(yǔ)句塊里面添加關(guān)鍵字group就能進(jìn)行分組。分組后的結(jié)構(gòu)如下圖所示。

JWT校驗(yàn)

接下來(lái)我們?cè)賮?lái)看一下api文件中怎么開(kāi)啟jwt認(rèn)證
在配置文件demo-api.yaml中添加jwt配置

在config文件中添加一個(gè)JWT認(rèn)證需要的密鑰和過(guò)期時(shí)間配置

JwtAuth struct { // JWT 認(rèn)證需要的密鑰和過(guò)期時(shí)間配置  

    AccessSecret string  

    AccessExpire int64  

}

使用方法也很簡(jiǎn)單，我們?cè)贎service語(yǔ)句塊中添加jwt關(guān)鍵字，使用Auth即可開(kāi)啟jwt。

通過(guò)測(cè)試請(qǐng)求我們可以看見(jiàn)返回401沒(méi)有權(quán)限，說(shuō)明jwt校驗(yàn)生效了

路由規(guī)則

路由必須以 / 開(kāi)頭 2. 路由節(jié)點(diǎn)必須以 / 分隔
路由節(jié)點(diǎn)中可以包含 :，但是 : 必須是路由節(jié)點(diǎn)的第一個(gè)字符，: 后面的節(jié)點(diǎn)值必須要在結(jié)請(qǐng)求體中有 path tag 聲明，用于接收路由參數(shù)，詳細(xì)規(guī)則可參考路由參數(shù)^[6]。4. 路由節(jié)點(diǎn)可以包含字母、數(shù)字(goctl 1.5.1 支持，可參考新版 API 解析器使用^[7])、下劃線、中劃線

參數(shù)規(guī)則

接收規(guī)則說(shuō)明生效范圍示例jsonjson 序列化請(qǐng)求體&響應(yīng)體json:"foo"path路由參數(shù)請(qǐng)求體path:"id"formpost 請(qǐng)求的表單(支持 content-type 為?form-data?和?x-www-form-urlencoded) 參數(shù)請(qǐng)求接收標(biāo)識(shí)，get 請(qǐng)求的 query 參數(shù)接收標(biāo)識(shí)請(qǐng)求體form:"name"headerhttp 請(qǐng)求體接收標(biāo)識(shí)請(qǐng)求體header:"Content-Length"

中間件聲明

想要使用中間件，可以在@server語(yǔ)句塊中使用關(guān)鍵字middleware生成一個(gè)中間件模板。
TIP：需要注意的是中間件首字母必須大寫(xiě)，否則無(wú)法被其他包導(dǎo)入。

在svc包的servicecontext.go中注冊(cè)中間件

生成的中間件代碼如下

API Import

當(dāng)我們的業(yè)務(wù)體量上來(lái)后，api文件可能會(huì)越來(lái)越大，又或者我們有一些公共結(jié)構(gòu)體。如果我們都寫(xiě)在同一個(gè)api文件中，那么api文件將會(huì)變得非常巨大，不易閱讀和維護(hù)，這時(shí)候就需要拆解api文件，通過(guò)import來(lái)導(dǎo)入。

syntax

版本信息，import中的版本信息必須與被import的api版本信息一樣。
規(guī)范寫(xiě)法

syntax = "v1"

我們創(chuàng)建一個(gè)新的文件demo1.api，并且將分組寫(xiě)到這個(gè)api文件下。
因?yàn)槲覀兊恼?qǐng)求體和響應(yīng)體是公共結(jié)構(gòu)體，都寫(xiě)在demo.api下面了，我們通過(guò)import “demo.api”就能導(dǎo)入demo.api。

完整的api文件模板

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的服務(wù)  
service demo-api {  
    @handler DemoHandler  
    post /from (Request) returns (Response)  
}  

// 分組2的服務(wù)  
@server (  
    prefix :/demo1  
    group: demo_api1  
)  
service demo-api {  
    @handler DemoHandler1  
    get /from/:name(Request) returns (Response)  
}