Zan Thrift IDL 设计规范¶

thrift IDL项目 目录结构¶

  1. ├── composer.json
  2. ├── gen_java.sh # Java SDK生成脚本
  3. ├── gen_php.sh # PHP SDK 生成脚本
  4. ├── gen-php # PHP SDK 生成目录
  5. ├── thrifts # IDL目录
  6. │   └── credit # 应用的领域,具体模块名称
  7. │       └── base # 分层, core, base
  8. │           ├── common # 这个应用的领域的分层内的通用实体和业务异常
  9. │           │   ├── entity
  10. │           │   └── exception
  11. │           ├── policy # 子领域
  12. │           │   ├── constant # 常量定义
  13. │           │   ├── entity # 实体定义
  14. │           │   ├── exception # 业务异常
  15. │           │   └── service # 服务定义

Service IDL 模板¶

service的方法定义, 需要采用 /* / 将注释文本包围,并且在每个参数的序号前, 使用这个格式给出这个参数的注释,对于异常也需要用同样的方式给出

  1. namespace nova com.youzan.scrm.credit.base.service
  2. /**
  3.  * 首行是命名空间定义, 命名空间与目录名是保持一致的
  4.  * com.youzan.scrm 为SCRM的固定前缀，credit 为领域名称
  5.  */
  6.  
  7. /**
  8.  * 引入接口用到的 DTO 定义
  9.  * 以相对于 thrifts 目录引入 DTO 文件，IDE 可以识别并高亮
  10.  */
  11. include "credit/base/entity/account/CreditAccountDTO.thrift"
  12. include "credit/base/entity/account/CreditAccountModificationDTO.thrift"
  13. include "credit/base/entity/account/CreditAccountQueryDTO.thrift"
  14. include "credit/base/exception/common/CreditBaseException.thrift"
  15. include "credit/base/exception/common/NegativeCreditException.thrift"
  16.  
  17. service CreditAccountService {
  18.  
  19.     /**
  20.      * 增加积分
  21.      */
  22.     CreditAccountModifiedResultDTO.CreditAccountModifiedResultDTO increaseCredit(
  23.         /** 账户查询参数 */
  24.         1:CreditAccountQueryDTO.CreditAccountQueryDTO accountQuery,
  25.         /** 积分变动对象 */
  26.         2:CreditAccountModificationDTO.CreditAccountModificationDTO modification
  27.     ) throws (
  28.         /** 未定义积分异常 */
  29.         1:CreditBaseException.CreditBaseException e
  30.     );
  31.  
  32.     /**
  33.      *  消耗积分
  34.      */
  35.     CreditAccountModifiedResultDTO.CreditAccountModifiedResultDTO decreaseCredit(
  36.         /** 账户查询参数 */
  37.         1:CreditAccountQueryDTO.CreditAccountQueryDTO accountQuery,
  38.         /** 积分变动对象 */
  39.         2:CreditAccountModificationDTO.CreditAccountModificationDTO modification
  40.     ) throws (
  41.         /** 未定义积分异常 */
  42.         1:CreditBaseException.CreditBaseException e,
  43.         /** 积分不可为负异常 */
  44.         2:NegativeCreditException.NegativeCreditException negativeE
  45.     );
  46. }

  • 尽量以 CRUD的顺序定义接口，保证同类型的接口存放位置是相邻的，便于查找

  • 接口

    • 动宾结构
    • 表意，如 getByCardAlias
    • 通常用 getBrief 表示获取简要信息
    • 所有接口都必须定义抛出的异常类型

  • 返回值

    • 一般情况下，create 接口返回创建的对象的完整 DTO，update, delete之类的操作接口返回布尔值
    • 列表接口，若需要返回分页信息，返回值 DTO 名称使用 XXXPaginationDTO格式
    • 根据 ID 获取列表，返回 map

  • 参数

    • 接口定义要明确操作主体，一般地操作主体的参数都放在第一位，如 kdtId

    • 接口一旦有使用方使用了，不得随意调整参数的顺序值

    • 参数值若有限，必须使用枚举类型定义

    • 参数值为不可重复数值列表（如 id 列表），请使用 set 类型

    • 参数值为数字，请酌情使用 i16 i32 i64

    • 带复杂查询条件、排序条件、分页要求的接口参数建议：

  1. 1:i32 kdtId,
  2. 2:CardQueryDTO.CardQueryDTO query,
  3. 3:map order,
  4. 4:i32 page,
  5. 5:i32 pageSize
  1. - 查询条件命名成 XXXQueryDTO
  2. - 排序条件定义成 map，key 为排序字段，value 为 DESC or ASC

  • 不要使用 json 字符串传值，请使用类型组合的方式

  • 入参与返回值使用的 DTO 请分别定义，通常入参的 DTO 会命名成XXXCreateDTO, XXXUpdateDTO

DTO IDL 模板¶

model的每个字段, 注释也是使用 /* / 包围,并且每个属性都需要写出是必须还是可选

  1. namespace nova com.youzan.scrm.credit.base.account.entity
  2.  
  3. include "credit/base/common/entity/CreditCycleDTO.thrift"
  4. include "credit/base/common/entity/CreditStatusDTO.thrift"
  5. include "credit/base/source/entity/SourceBusinessQueryDTO.thrift"
  6. include "credit/base/source/entity/SourceUserQueryDTO.thrift"
  7.  
  8. /**
  9.  * 用于描述一个用户, 在一个商家的一个积分定义以及一个积分策略下的积分概览信息
  10.  */
  11. struct CreditAccountDTO {
  12.  
  13.     /** 账户ID */
  14.     1:required i64 accountId;
  15.  
  16.     /**
  17.      * 外部商家描述
  18.      */
  19.     2:required SourceBusinessQueryDTO.SourceBusinessQueryDTO business;
  20.  
  21.     /**
  22.      * 外部用户描述
  23.      */
  24.     3:required SourceUserQueryDTO.SourceUserQueryDTO user;
  25.  
  26.     /**
  27.      * 积分定义ID
  28.      */
  29.     6:required i64 definitionId;
  30.  
  31.     /**
  32.      * 策略ID
  33.      */
  34.     7:required i64 policyId;
  35.  
  36.     /**
  37.      * 当前积分状态
  38.      */
  39.     101:required CreditStatusDTO.CreditStatusDTO status;
  40.  
  41.     /**
  42.      * 下一次将要过期的积分的信息
  43.      */
  44.     102:optional CreditCycleDTO.CreditCycleDTO willExpire;
  45.  
  46.     /**
  47.      * 最后一次过期的积分的信息
  48.      */
  49.     103:optional CreditCycleDTO.CreditCycleDTO lastExpired;
  50.  
  51.     /**
  52.      * 创建积分账号的时间, UNIX时间戳, 以秒计
  53.      */
  54.     201:optional i64 createdAt = 0;
  55.  
  56.     /**
  57.      * 积分账号更新的时间, UNIX时间戳, 以秒计
  58.      */
  59.     202:optional i64 updatedAt = 0;
  60. }
  • 必须显式的声明字段是required和optional, 其中
    • required不允许有默认值
    • optional可以有默认值
  • 请根据实际情况使用各种数据类型，特别是 map, set, list以及自定义的枚举类型
  • 字段的顺序值不得随意调整, 并建议进行一定的分段以容纳业务上的新字段(见上面例子, 7和101中间分开了很多空余,足够给未来添加新的字段使用并且可以维持一定的逻辑顺序)
  • 几种特殊约定的 DTO 命名，用途在接口定义一节已说明
    • XXXCreateDTO
      • 不会包含 kdtId, uid 等主体参数
    • XXXUpdateDTO
      • 不会包含 kdtId, uid 等主体参数
    • XXXQueryDTO
    • XXXListItemDTO
    • XXXPaginationDTO
  1. struct XXXPaginationDTO {
  2.     1:i64 total;
  3.     2:i32 page;
  4.     3:i32 pageSize;
  5.     4:list<XXXListItemDTO.XXXListItemDTO> items;
  6. }

Exception IDL 模板¶

Exception没必要带上对于属性的注释,但是强制要求message和code两个属性直接给出默认值

  1. namespace nova com.youzan.scrm.credit.base.exception.common
  2.  
  3. exception NegativeCreditException {
  4.  
  5.     1:optional string message = '积分不能为负'
  6.  
  7.     2:optional i32 code = 140000000
  8.  
  9. }

原文: http://zanphpdoc.zanphp.io/nova/IDL_spec.html