api/* 编写规范

接口书写规范

必须遵循此规范，才能自动识别接口相关信息
@desc/@description 接口说明
@param 参数说明
@return/@returns 返回值说明

/**
 * @desc 获取服务详情
 * @param sid 服务ID
 * @returns {Promise<any>}
 */
export async function getServiceInfo(sid) {
    return await dajxHttp.post({
        url: '/api/service/info',  // <-------- 注意，这里的 url 必须放第一个
        data: {sid}
    });
}

如果参数独立声明，必须名为 params，同样 url 必须放第一个

export async function dispatchOrder(orderId, staffId) {
  let params = {
    url: '/cmsapi/admin/service/edit_order.html',
    data: {
      'staff_id': staffId,
    }
  };
  params.url += '?id=' + orderId; // <-------------如果需要修改，独立出来
  return dajxHttp.cms(params);
}

支持不传递某个参数
- 页面上调试接口时，勾选no default则不传递没有生成值或者没有自定义值的参数（有默认值依然不传递）
- 批量请求接口时，配置geneArgs的noDef参数为true时，则不传递没有生成值的参数示例配置：（本接口配置了noDef参数为true，批量请求接口时只会传递product_category_id参数）

    'productList': {
        '__proto__': base.productList,
        'api': apis.productList,
        'desc': " [商城模块]商品列表",
        'url': '/api/product/list',
        'defaults': {
          is_recommend: false,
          pageSize: '10',
          page: '1',
          product_category_id: '',
        },
        "nullList": ["data.info.0.productPromotion"],
        'generated': {},
        'user': {},
        'geneArgs': [
          {
            'scene': 'default',
            'desc': '',
            'type': NORMAL,
            'noDef':true,
            'func': async (ctx) => {
              ctx.generated = {
                product_category_id: 1
              };
            }
          }
        ],
      },

如果注释中含有__ignore则忽略对此函数的解析

/**
 * @desc __ignore
 */
 function post (data) {
  data.url = baseURL + data.url;
  return POST(data);
}

返回值注释规范

1 将一个典型的返回值复制到 @returns 字段，并对其进行任何必要的注释，注意必须符合 js 语法
- 注意 @returns 要加上 {Promise<any>}，或者 {Promise<*>}
- 用这里处理过的返回值
2 对每个必要的可变字段进行注释，如 x 字段可变，则在 x 同级添加 __x 字段，取值可以是以下几种：
- t(type): 不校验类型
- n(null): 如果样本配置为 Object/Array, 返回值可以是 null
- k(key): 返回值可以不包含此 key
- 以上三种可以组合使用, eg：{'a': {}, '__a': 'ntk'}
- i(ignore): 忽略此节点，以及所有子孙节点（相当于 'ntk' 三种的组合 + 递归）

      // 返回值中不管pay_info 是何种情况都会忽略校验
      "__pay_info": "i",
      "pay_info": {
        "appid": "wx1288370bcddf64a6", // appid
        "partnerid": "1561352391",
        "prepayid": "wx071723074162042b33102e23ffc93c0000",
        "timestamp": "1607332987",
        "noncestr": "i5B6NsCDqXWu23wd",
        "package": "Sign=WXPay",
        "sign": "CAC7B52AE528B9CAE9E350F5CF76E830" // 签名
      }

注意：user/* 中配置 nullList, keyList, typeList 的方式仍然支持

more eg

{'a': {}, "__a": 'n'} 返回值中 a 可能是 null：{'a': null}
{'a': '', "__a": 't'} 返回值中 a 的类型不确定：{'a': 1}, {'a': '1'}, {'a': {}} ...
{'a': [1], "__a": 'k'} 返回值中 a 可能是空数组，或者无 a：{'a': []}, {}
某些极端情况下，比如下面的配置，当返回值为 {'a': [1]} 时，必需改为 'i':

  {
    "__a": "ntk",
    'a': [
      {'b': 1}
    ]
  },

powder-api

接口书写规范

返回值注释规范

more eg

用户目录