# Xtils 建设指南

作者: 谭辉

# 仓库地址

仓库：http://elb-791125809.cn-northwest-1.elb.amazonaws.com.cn:5335/xdata/xdata-FE/component-library/dist-base

目前Xtils作为公司基础研发库的一个 package 进行管理，并没有独立的仓库。

在仓库目录中，packages/utils即为Xtils源码目录。

需要为Xtils贡献代码时，请以仓库 dev 分支中packages/utils目录作为最新源码，进而再此基础上贡献代码。

# Xtils 源码结构

# 目录结构说明

在Xtils中，src目录下存放各类函数，tests目录下存放函数的单元测试用例

# 函数编写说明

Xtils中的功能函数以javascript编写，且需要为每个函数单独提供TS 类型声明文件，TS 声明文件需放在 JS 功能函数同一目录下，TS 声明文件名需与 JS 函数文件名一致，如图所示：

函数分类

现目前Xtils共有以下几大类函数，分类规则为：以函数处理的数据类型作为划分
1. array - 处理数组类型数据
2. assert - 对数据类型的判断类的函数
3. browser - 浏览器 API 的增加
4. deprecated - 不推荐使用的函数，由于历史原因，一些老旧函数不推荐使用，放置此目录下
5. download - 文件下载类函数
6. env - 获取、设置环境变量类函数
7. number - 处理数字类型的函数
8. object - 处理对象类型的函数
9. url - 处理 url 的函数
10. shared - 不对外开放的函数，内部函数之间可能需要用到的共用的逻辑处理函数，放置在此类
11. others - 不属于以上类别的函数暂放此目录中
函数导出

每一个功能函数皆以默认导出形式进行导出，即：
```
export default function () {}
// 或者
function example() {}

export default example;
```
1
2
3
4
5
新增的功能函数除了在本身JS文件中使用默认导出，同时还需要在src/index下添加一个导出接口。如下图所示：

注意：为了实现函数库按需加载，具名函数导出的名称需与 JS 文件名一致，且文件名须为小驼峰命名规则

注意：由于 xtils 作为产品研发大仓库的一部分，仓库采用的monorepo方式进行管理，如果在贡献函数功能时需要安装外部依赖库，请安装在 utils 这个 package 下，但由于 xtils 本身作为一个轻量函数库，请尽量减少对第三方库的依赖：
```
pnpm add xxx -F utils
```
1

# 单元测试

单元测试所用框架为jest
如果新增功能函数，必须为函数编写单元测试文件，要有足够的覆盖度。如果修改功能函数，也要修改对应的测试用例添加覆盖单元。
单元测试文件中导入的函数需从src/index.js文件中导入，而不是从函数文件所在位置导出，如下：
```
// converUnit.test.js
import { convertUnit } from '../src';
```
1
2

# 提交 PR

在 gitlab 仓库中提交 MergeRequest, 目标分支选择 Dev 分支
在 MR 的信息填写相关信息

如果是为 xtils 新增函数：
1. title 请填写：新增 xxx 函数
2. description 请填写函数应用场景
如果是为 xtils 修复 bug 或者增强函数：
1. title 请填写：修复 xxx 函数 xxx 问题或 [xxx 函数]：支持 xxx 功能
2. description 请填写修复问题的详情或增加的函数功能详情