yp-feishu-ins

介绍

一个专为飞书开发的工具库，提供了基于 Axios 的二次封装网络请求库和丰富的工具函数集合。支持 TypeScript，开箱即用。

特性

• 🚀 现代化构建: 基于 Vite 构建，支持 ESM 和 CommonJS
• 📦 TypeScript 支持: 完整的类型定义，提供良好的开发体验
• 🌐 网络请求: 基于 Axios 的二次封装，内置飞书 API 支持
• 🛠️ 工具函数: 丰富的日期、数组、对象处理工具
• 📅 日期处理: 基于 dayjs 的时间处理工具
• 🔧 灵活配置: 支持自定义配置和拦截器

安装教程

# npm
npm install yp-feishu-ins

# yarn
yarn add yp-feishu-ins

# pnpm
pnpm add yp-feishu-ins

使用说明

HTTP 请求

import { fsRequest, Request } from 'yp-feishu-ins'

// 使用内置的飞书请求实例（baseURL: https://open.feishu.cn/open-apis）
const response = await fsRequest.get('/auth/v3/tenant_access_token/internal')

// 创建自定义请求实例
const api = new Request({
  baseURL: 'https://api.example.com',
  timeout: 5000,
})

// 设置请求头（如飞书 API 认证）
api.setHeaders('Bearer your-token', {
  'Content-Type': 'application/json'
})

// 或者设置完整的请求配置
api.setConfReq({
  headers: {
    'Authorization': 'Bearer your-token',
    'Content-Type': 'application/json'
  }
})

// GET 请求
const users = await api.get('/users', { page: 1, limit: 10 })

// POST 请求
const newUser = await api.post('/users', {
  name: 'John Doe',
  email: '[email protected]',
})

// PUT/PATCH 请求
const updatedUser = await api.put('/users/1', { name: 'Jane Doe' })
const patchedUser = await api.patch('/users/1', { status: 'active' })

// DELETE 请求
const result = await api.delete('/users/1')

日期时间工具

import { dayjs } from 'yp-feishu-ins'
import { isTimeInRange, getWeekEnd, isTimeStr } from 'yp-feishu-ins/tool'

// 使用 dayjs 进行日期处理
const now = dayjs()
const formatted = now.format('YYYY-MM-DD HH:mm:ss')

// 判断时间是否在范围内
const inRange = isTimeInRange('2024-01-15', '2024-01-01', '2024-01-31')
const inRangeInclusive = isTimeInRange('2024-01-01', '2024-01-01', '2024-01-31', 'all')

// 获取指定时间的周六和周日
const { saturday, weekend, day } = getWeekEnd('2024-01-15')
console.log(saturday) // '2024-01-13'
console.log(weekend)  // '2024-01-14'
console.log(day)      // 1 (周一)

// 验证时间字符串
const isValid = isTimeStr('2024-01-15') // true
const isValidTimestamp = isTimeStr(1705276800000) // true

数组和对象工具

import {
  isArr,
  chunk,
  reverseObj,
  getGuid,
  wait,
  numToCn,
  cnToNum
} from 'yp-feishu-ins/tool'

// 判断是否是数组且长度符合要求
const valid = isArr([1, 2, 3], 2) // true
const invalid = isArr([], 1) // false

// 数组分块
const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
const chunks = chunk(numbers, 3) // [[1,2,3], [4,5,6], [7,8,9], [10]]

// 反转对象键值对
const statusMap = { active: '激活', inactive: '未激活' }
const reversed = reverseObj(statusMap) // { '激活': 'active', '未激活': 'inactive' }

// 生成 UUID
const id = getGuid() // 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'

// 异步等待
await wait(1000) // 等待 1 秒

// 数字转中文
const chinese1 = numToCn(12) // '十二'
const chinese2 = numToCn(123) // '一百二十三'
const chinese3 = numToCn(1234) // '一千二百三十四'

// 中文转数字
const number1 = cnToNum('十二') // 12
const number2 = cnToNum('一百二十三') // 123
const number3 = cnToNum('一千二百三十四') // 1234

日历工具

import { createCalendar } from 'yp-feishu-ins/tool'

// 根据假期数组生成日历
const holidays = [
  {
    start_time: '2024-01-01',
    end_time: '2024-01-03',
    summary: '元旦假期'
  },
  {
    start_time: '2024-02-10',
    end_time: '2024-02-17',
    summary: '春节假期'
  }
]

const calendar = createCalendar(holidays)
// 返回包含每一天详细信息的数组
console.log(calendar[0])
// {
//   time: '2024-01-01',
//   year: 2024,
//   month: 1,
//   day: 1,
//   summary: '元旦假期',
//   isWork: false
// }

API 文档

Request 类

构造函数

import { Request, fsRequest } from 'yp-feishu-ins'

// 创建自定义实例
const api = new Request(config?: RequestConfig)

// 使用内置飞书实例
fsRequest // baseURL: 'https://open.feishu.cn/open-apis'

配置方法

• setHeaders(authorization: string, headers: object) - 设置请求头
• setConfReq(config: RequestConfig) - 设置请求配置

HTTP 方法

• get<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ResponseData<T>>
• post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ResponseData<T>>
• put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ResponseData<T>>
• patch<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ResponseData<T>>
• delete<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ResponseData<T>>

日期时间工具

dayjs

• dayjs - 导出的 dayjs 实例，支持所有 dayjs 方法

时间判断

• isTimeInRange(targetTime, startTime, endTime, inclusive?) - 判断时间是否在范围内
  • inclusive: 'start' | 'end' | 'all' | undefined
• isTimeStr(val: any): boolean - 验证是否为有效的时间字符串或时间戳

时间计算

• getWeekEnd(time?: string | Date | Dayjs) - 获取指定时间的周六和周日
  • 返回: { saturday: string, weekend: string, day: number }

数组和对象工具

数组操作

• isArr(val: any, len?: number): boolean - 判断是否是数组且长度大于等于指定值
• chunk<T>(array: T[], size?: number): T[][] - 将数组按指定大小分块，默认 10

对象操作

• reverseObj<T>(obj: T): Record<string, keyof T> - 反转对象的键值对

工具函数

• getGuid(): string - 生成 UUID
• wait(time?: number): Promise<void> - 异步等待，默认 1ms
• numToCn(num: number): string - 数字转中文，如 12 → '十二'
• cnToNum(chinese: string): number - 中文转数字，如 '十二' → 12

日历工具

createCalendar

createCalendar(
  arr: Array<{
    start_time: string
    end_time: string
    summary: string
  }>,
  arrSummary?: string[]
): Array<CalendarItem>

生成日历数据，arrSummary 默认为 ['补班', '补班日', '可加班']

返回的 CalendarItem 结构：

{
  time: string        // 'YYYY-MM-DD'
  year: number
  month: number
  day: number
  summary: string     // 日程说明
  isWork: boolean     // 是否是工作日
}

开发指南

环境要求

• Node.js >= 14.0.0
• pnpm (推荐) / npm / yarn

本地开发

# 克隆项目
git clone https://gitee.com/workshop_1/feishu-tool.git
cd feishu-tool

# 安装依赖
pnpm install

# 开发模式（启动 Vite 开发服务器）
pnpm run dev

# 运行测试
pnpm test

# 运行测试并查看 UI
pnpm run test:ui

# 构建项目
pnpm run build

# 预览构建结果
pnpm run preview

项目结构

src/
├── index.ts              # 主入口文件
├── lib/
│   ├── request/          # HTTP 请求模块
│   │   ├── index.ts      # Request 类实现
│   │   └── types.d.ts    # 类型定义
│   ├── dayjs/            # 日期处理模块
│   │   └── index.ts      # dayjs 配置
│   └── tool/             # 工具函数模块
│       └── index.ts      # 各种工具函数
└── types/                # 全局类型定义

测试

项目使用 Vitest 进行测试，测试文件位于 tests/ 目录：

# 运行所有测试
pnpm test

# 监听模式运行测试
pnpm test --watch

# 生成测试覆盖率报告
pnpm test --coverage

发布到 NPM

发布前请确保已切换到 npm 官方镜像源

# 登录 npm
npm login

# 构建项目（发布前会自动执行）
pnpm run build

# 发布到 npm
npm publish

# 版本管理
npm version patch   # 补丁版本 (1.0.0 -> 1.0.1)
npm version minor   # 次要版本 (1.0.0 -> 1.1.0)
npm version major   # 主要版本 (1.0.0 -> 2.0.0)

# 发布新版本
npm publish

发布检查清单

• [ ] 所有测试通过
• [ ] 更新版本号
• [ ] 更新 CHANGELOG
• [ ] 确认构建产物正确
• [ ] 切换到 npm 官方源

贡献指南

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本仓库
2. 创建特性分支: git checkout -b feature/your-feature-name
3. 提交更改: git commit -am 'Add some feature'
4. 推送到分支: git push origin feature/your-feature-name
5. 创建 Pull Request

贡献类型

• 🐛 Bug 修复: 修复现有功能的问题
• ✨ 新功能: 添加新的工具函数或功能
• 📚 文档: 改进文档和示例
• 🎨 代码优化: 重构和性能优化
• 🧪 测试: 添加或改进测试用例

开发规范

• 遵循现有的代码风格
• 为新功能添加相应的测试
• 更新相关文档
• 确保所有测试通过

更新日志

查看 Releases 了解版本更新详情。

许可证

本项目基于 MIT 许可证开源。

相关链接

• Gitee 仓库
• NPM 包
• 问题反馈

如果这个项目对你有帮助，请给个 ⭐️ 支持一下！