daip-calligraphy-frontend-shared-api v3.3.0-20230306

书法项目前端公用的 API

背景

随着书法项目的前端项目横向增加，目前已经有 '运营端'、'校管端'、'授课端'、'家长端小程序'、'教管端小程序' 五个客户端之多，而它们很多时候使用的后端接口是相同，这意味着每个客户端都会有重复的接口定义胶水代码，本仓库为消除这些重复的代码应运而生。

特性

本项目主要包含两个特性：

• 根据 yapi 文档生成 API 的 TS 定义代码，这主要归功于 yapi-to-typescript 提供的能力。
• 由 Tag 触发的自动化的包发布。

由于代码是通过 yapi 文档自动生成，我们在此视 yapi 为接口的唯一事实标准，因而对 yapi 文档的撰写者有更高的要求。

若生成的 TS 代码与实际不符，那么需要对应的文档作者进一步完善文档，这个过程可能会不断反复，所以 shared-api 包可能在一个迭代版本里发布多次，而在使用包的项目中只需要简单地 npm update @daip-calligraphy/frontend-share-api。

发布

若 yapi 文档有更新需要包的发布时，在本仓库中添加新的 tag 即可。Tag 会触发 pipeline 来自动化获取 yapi 文档生成新的包。对于 tag 有特殊的要求：

• tag 必须打在 main 或 dev 分支上。
• tag 必须为 x.y.z-yyyymmdd 的格式，其中 x.y.z 为当前产品迭代的版本，而 yyyymmdd 为当前日期，例如：3.3.0-20230219。这样的 tag 有助于追踪每个版本的 API 变化。
• 如果在同一天发布多次，那么还可以添加额外的后缀数字，例如: 3.3.0-20230219.1。
• 以上格式之外的的 tag 都不会触发发布的 pipeline。

使用

安装

在 terminal 执行命令 npm install @daip-calligraphy/frontend-shared-api。

初始化

在 src/main 文件中加入以下代码

import { initSharedAPI } from '@daip-calligraphy/frontend-shared-api';
import { http } from '@/api/http';

initSharedAPI({
  http: http,
  // shareAPI 的路径与 yapi 文档中相同，若 http 方法设置了默认的 baseURL 需要手动覆盖掉。
  overrideConfig: { baseURL: '' },
});

在 Service 中调用 SharedAPI

在 Service 中可以通过 @daip-calligraphy/frontend-shared-api 访问到 API 的函数和类型

import { getApiV2OperationContent, GetApiV2OperationContent } from '@daip-calligraphy/frontend-shared-api';

export const getContent = function (params: GetApiV2OperationContentRequest) {
  const [err, res] = await getApiV2OperationContent({
    id: params._id,
  });
  // ...
}