api-runtime

@ali/api-runtime

@ali/api-loader 的运行时支持, 目前包含两种基础类型请求 ajax 和 jsonp 和一个 mock

ajax kind

/**
 * @kind ajax
 * @host https://example.alibaba-inc.com
 * @basUrl /api/v1 
 */
declare class ChargeDataApi {
  /**
   * 根据用户名称和年份查询用电分布
   * @url /chart.json
   * @method get
   * @param user 查询的用户
   * @param year 查询的年份
   * @paramsSerializer indices
   */
  getChargeData(user: string, year: number): Promise<{ chart: IChargeData[] }>;
}

配置项说明

注释或注解

• @kind 指定该函数接口使用 ajax 请求
• @host 请求域名 可选, 不填写表示使用相对当前 web 应用
• @baseUrl 基础相对路径 可选
• @url 请求的接口 必选. 如果该值以 http(?):// 开头则不拼接 host/baseUrl
• @method get/post/put/delete 基本的ajax请求类型
• @param 函数参数注释,标准 ts/js 注释项. 可选,提高代码可读性
• @paramsSerializer 可选. 可填 indicate | brackets | repeat | comma. 当 method 是 get 时生效, 用于指定如何序列化 get 方法的 query 参数. 详情参考 https://web.npm.alibaba-inc.com/package/qs

注解

• @ajax.url(url: string) url
• @ajax.willFetch(hooks: (reqData: AxiosRequestConfig) => Promise | AxiosRequestConfig)
• @ajax.didFetch(hooks: (reqData: AxiosResponse) => Promise | AxiosResponse);

path variable

• url 支持 path variable 形式如:

  /**
   * 根据用户 id 查询信息, 函数参数会作为 path_param 嵌入到 url 中
   * @url /{uid}/audiocards.json
   * @param uid 用户工号
  */
  getAudioCards(uid: string): Promise<TVideoCards>;

jsonp kind

基于 @ali/shimmer

declare class ChargeDataApi {
  /**
   * 根据用户名称和年份查询用电分布
   * @kind jsonp
   * @url /chart.json
   * @prefix __jp
   * @timeout 60000
   * @param user 查询的用户
   * @param year 查询的年份
   */
  getChargeData(user: string, year: number): Promise<{ chart: IChargeData[] }>;
}

注释或注解配置项

• @prefix jsonp 的 callback 前缀
• @timeout 超时时间
• @name 回调函数名, 可选 不写时使用 prefix+(Date.now() + parseInt(Math.random() * 5))

mock 使用

• 开发模式下(api-loader配置项 mock=true 即为开发模式. 参考 api-loader的说明), 如果 window.__mock__ = 1 或 class/method 有注释 @mock true, 则该接口会根据声明的 typescript 返回类型信息生成随机内容.
• html 中如果引用了 mockjs, <script src="https://g.alicdn.com/code/lib/Mock.js/1.0.0/mock-min.js"></script> 则 string 类型支持注释项 @mockjs, 例如:

export type User = {
  /** @mockjs cname */
  name: string,
  /** @mockjs ctitle */
  title: string,
  /** @mockjs image */
  icon: string,
  /** @mockjs city */
  home: string,
  /** @mockjs email */
  email: string
}[]

更多 mockjs 项如 dataimage 等请参考 mockjs方法

changelog

0.1.5 ✨enum 类型支持; mock 增强支持数组定义长度 0.1.2 ✨ajax spread 和 path_variable 支持混用 ✨mock fix any 类型 mock 出错 0.1.0 ✨ajax 增加 spread 配置项 https://yuque.antfin-inc.com/recore/docs/api-loader#ae4dcc0a ✨ajax 增加 didCatch 配置项 0.0.11 ✨注解返回类型自适应,避免注解 class 和 function 报错 void 不适用于 xxx 0.0.9 ✨支持 mockjs ✨支持 path variable 0.0.8 ✨支持类型组合/类型继承 ✨增加注解支持, 增加注解 d.ts 声明