Thrift-HTTP 映射的 IDL 规范

struct Item{
    1: optional i64 id(go.tag = 'json:"id"') // 对于嵌套结构体，如果要设置序列化key,使用gotag 如 `json:"id"`
    2: optional string text
}
typedef string JsonDict
struct BizRequest {
    1: optional i64 v_int64(api.query = 'v_int64') // 对应HTTP query中的v_int64, 且值范围为(0,200)
    2: optional string text(api.body = 'text') // 对应序列化key = text
    3: optional i32 token(api.header = 'token') // 对应HTTP header中的token
    4: optional JsonDict json_header(api.header = 'json_header')
    5: optional Item some(api.body = 'some') // 对应一级key = some
    6: optional list<ReqItem> req_items(api.query = 'req_items')
    // api.query仅支持逗号相隔的list,其他复杂类型不支持
    7: optional i32 api_version(api.path = 'action') // 对应uri的path参数
    8: optional i64 uid(api.path = 'biz') // 对应uri的path参数
    9: optional list<i64> cids(api.query = 'cids')
    // 对应query里面逗号隔开的数字, 如 cids=1,2,3,4仅支持list<i64>、list<i32>
    10: optional list<string> vids(api.query = 'vids')
}

// 最终将把BizResponse json序列化之后作为给客户端的返包
struct RspItem{
    1: optional i64 item_id // 默认被以字段名作key序列化，等价于使用gotag `json:"item_id"`
    2: optional string text
}
struct BizResponse {
    1: optional string T  (api.header= 'T')
    // 该字段将填入给客户端返回的header中
    2: optional map<i64, RspItem> rsp_items  (api.body='rsp_items')
    // 一级key = 'rsp_items'
    3: optional i32 v_enum  (api.none = 'true') // 该注解value通常写true，其它情况与不写该注解等价
    4: optional list<RspItem> rsp_item_list  (api.body = 'rsp_item_list')
    // 业务自己指定了HTTPCode,  如果没有指定, baseResp.StatusCode=0 -> HTTPCode=200,  其他 HTTPCode=500
    5: optional i32 http_code  (api.http_code = 'true')    //对应 response HTTP Code
    6: optional list<i64> item_count (api.header = 'item_count') // 当设置header时以逗号相隔的列表
    7: optional string token (api.cookie = 'token') // 对应 response Cookie 字段
}

service BizService{
    // 例子1： get请求
    BizResponse BizMethod1(1: biz.BizRequest req)(
        api.get = '/life/client/:action/:biz',
        api.baseurl = 'ib.snssdk.com',
        api.param = 'true',
        api.category = 'demo'
    )

    // 例子2:   post请求
    BizResponse BizMethod2(1: biz.BizRequest req)(
        api.post = '/life/client/:action/:biz',
        api.baseurl = 'ib.snssdk.com',
        api.param = 'true',
        api.serializer = 'form'
    )

    // 例子3:   delete请求
    BizResponse BizMethod3(1: biz.BizRequest req)(
        api.post = '/life/client/:action/:biz',
        api.baseurl = 'ib.snssdk.com',
        api.param = 'true',
        api.serializer = 'json'
    )
}