@shencom/api v2.0.0-alpha.2

@shencom/api

描述....

install

pnpm add @shencom/request @shencom/api

# or

yarn add @shencom/request @shencom/api

Usage

Init

import { axiosBrowser } from '@shencom/request';
// import { axiosUniapp } from '@shencom/request';
import { init } from '@shencom/api';

const url = 'xxxx';

init(http, url);

Basic Usage

import { ApiGisShow } from '@shencom/api';

function getGisShow() {
  const { data } = await ApiGisShow({ ids: ['xxx'] });
  // console.log(data);
}

API

uaa

• 获取 sccode: ApiGetScCode;
• sccode 登录: ApiScCodeLogin;

• 使用 refreshToken 续期 token: ApiRefreshToken;

  • token 8 小时有效期
  • refreshToken 30 天有效期

• 更新系统用户信息

• 注册用户
• 用户名+密码登录:
• 手机号+密码登录: ApiPhoneAndPasswordLogin;
• 手机号+短信登录:
• 发送短信:

uaa-wechat

• 微信小程序登录: ApiWechatMiniLogin;
• 小程序手机号登录,并绑定手机号到系统用户（创建系统用户）
• 绑定微信用户登录: BaseWechatMiniBindPhone;
• 退出登录 (解除微信绑定)
• 微信公众号授权登录
• 更新微信用户信息
• 通过 openid 获取用户信息
• 判断是否关注公众号

wechat

• 获取公众号 JSSDK 配置: ApiWechatGetConfig

file

• oss 签名: ApiFileOssSign
• 将 oss 文件信息更新到数据库: ApiFileUpdate
• 服务器文件上传: ApiFileUpload
• 获取文件信息: ApiFileShow
• 单个文件上传
• 文件下载
• 检查图片是否含有违法违规或政治敏感内容
• 私有文件下载
• 私有上传指定 url 的文件
• 私有文件上传
• 私有 oss 签名
• 获取私有临时文件访问链接

gis

• 创建点位: ApiGisCreate;
• 获取点位: ApiGisShow;
• 更新点位
• 创建范围
• 更新范围
• 获取范围

cms

• 获取栏目: ApiCMSCategoryTree;
• 获取内容列表: ApiCMSArticlesIndex;
• 获取内容: ApiCMSArticlesShow;

AMap

• 高德-地理编码: ApiAMapGeocodeGeo;
• 高德-逆地理编码: ApiAMapGeocodeRegeo;
• 高德-天气查询: ApiAMapWeather;
• 高德-IP定位: ApiAMapIP;

QQMap

• 腾讯-地理编码: ApiQQMapGeocodeGeo;
• 腾讯-逆地理编码: ApiQQMapGeocodeRegeo;
• 腾讯-IP定位: ApiQQMapIP;

Helpers

ApiQueryHandler

• 说明: 查询参数生成格式方法（已废弃，建议使用 ApiQueryItemConstruct 和 ApiQueryConstruct 代替）

• 类型:

  function ApiQueryHandler(
    val: string | number | null,
    prop: string,
    operate?: OperateType | Operate,
    lr?: QueryLr
  ): SC.API.IndexQuery;
  
  function ApiQueryHandler(
    params: [string | number | null, string, (OperateType | Operate)?, QueryLr?][]
  ): SC.API.IndexQuery;

• 参数:

  • val: string | number | null - 查询的值
  • prop: string - 后端字段
  • operate?: OperateType | Operate - 筛选条件 (默认: 'string')
  • lr?: LrEnum - 逻辑关系(LrEnum.AND 或 LrEnum.OR)
  • params: val, prop, operate?, lr? - 查询参数数组
• 返回: SC.API.IndexQuery - 包含exps数组的查询索引对象

• 示例:

  // 基本用法
  ApiQueryHandler('1', 'active');
  // 返回: [{ exps: [{ value: '1', prop: 'active', operate: 'LIKE' }] }]
  
  // 使用特定操作类型
  ApiQueryHandler('2022-01-01', 'createdAt', 'rangeDateTime');
  // 返回: [{ exps: [{ value: '2022-01-01', prop: 'createdAt', operate: 'BTW' }] }]
  
  // 使用枚举值
  ApiQueryHandler(100, 'age', OperateEnum.EQ);
  // 返回: [{ exps: [{ value: 100, prop: 'age', operate: 'EQ' }] }]
  
  // 多条件查询
  ApiQueryHandler([
    [100, 'age', OperateEnum.EQ],
    ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
  ]);
  // 返回: [{ 
  //   exps: [
  //     { value: 100, prop: 'age', operate: 'EQ' },
  //     { value: '张三', prop: 'name', operate: 'LIKE', lr: 'and' }
  //   ] 
  // }]

Jsencrypt

• 说明: 密码加密
• 类型: (pwd: string) => string
• 参数:
  • pwd: 明文密码
• 返回: string
• 示例:

  const password = Jsencrypt('sc123456');

API 工具函数

sorts

排序参数生成工具函数,用于生成统一的排序参数格式。

ApiSortsConstruct

生成排序参数对象。

函数签名:

function ApiSortsConstruct(prop: string, type?: SortType): IIndexSorts;
function ApiSortsConstruct(params: [string, SortType?][]): IIndexSorts;

参数:

• prop: string - 排序字段名
• type: SortType - 可选的排序类型,可选值为 'ASC' 或 'DESC',默认为 'DESC'
• params: string, SortType? - 排序参数数组,每个元素为 字段名, 排序类型 的元组

返回值:

返回 IIndexSorts 类型的排序参数对象数组,每个对象包含:

• orderField: 排序字段名
• orderType: 排序类型('ASC' 或 'DESC')

示例:

// 单个字段排序
ApiSortsConstruct('createTime')
// 返回: [{ orderField: 'createTime', orderType: 'DESC' }]

// 指定排序类型
ApiSortsConstruct('createTime', 'ASC')
// 返回: [{ orderField: 'createTime', orderType: 'ASC' }]

// 多字段排序
ApiSortsConstruct([
  ['createTime', 'DESC'],
  ['updateTime', 'ASC']
])
// 返回: [
//   { orderField: 'createTime', orderType: 'DESC' },
//   { orderField: 'updateTime', orderType: 'ASC' }
// ]

// 多字段排序(使用默认排序类型)
ApiSortsConstruct([
  ['createTime'],
  ['updateTime']
])
// 返回: [
//   { orderField: 'createTime', orderType: 'DESC' },
//   { orderField: 'updateTime', orderType: 'DESC' }
// ]

ApiSortsDestructure

将排序对象转换为键值对格式。

函数签名:

function ApiSortsDestructure(sort: { orderField: string, orderType: string }): Record<string, string>;
function ApiSortsDestructure(sorts: Array<{ orderField: string, orderType: string }>): Record<string, string>;

参数:

• sort: { orderField: string, orderType: string } - 单个排序对象
• sorts: Array<{ orderField: string, orderType: string }> - 排序对象数组

返回值:

返回 Record<string, string> 类型的键值对对象，键为排序字段名，值为排序类型。

示例:

// 转换单个排序对象
ApiSortsDestructure({ orderField: 'createTime', orderType: 'DESC' })
// 返回: { "createTime": "DESC" }

// 转换排序对象数组
ApiSortsDestructure([
  { orderField: 'createTime', orderType: 'DESC' },
  { orderField: 'updateTime', orderType: 'ASC' }
])
// 返回: { "createTime": "DESC", "updateTime": "ASC" }

// 如果排序类型为空，则使用默认值 'DESC'
ApiSortsDestructure({ orderField: 'createTime', orderType: '' })
// 返回: { "createTime": "DESC" }

ApiSortsDelete

从排序数组中删除指定字段的排序条件。

函数签名:

function ApiSortsDelete(sorts: IIndexSorts, deleteProps: string | string[]): IIndexSorts | null;

参数:

• sorts: IIndexSorts - 排序条件数组
• deleteProps: string | string[] - 要删除的字段名(单个字符串或字符串数组)

返回值:

返回处理后的排序条件数组，如果结果为空数组则返回null。

示例:

// 删除单个字段的排序
const sorts = [
  { orderField: 'createTime', orderType: 'DESC' }, 
  { orderField: 'updateTime', orderType: 'ASC' }
];
ApiSortsDelete(sorts, 'createTime'); 
// 返回: [{ orderField: 'updateTime', orderType: 'ASC' }]

// 删除多个字段的排序
const sorts = [
  { orderField: 'createTime', orderType: 'DESC' }, 
  { orderField: 'updateTime', orderType: 'ASC' },
  { orderField: 'name', orderType: 'ASC' }
];
ApiSortsDelete(sorts, ['createTime', 'name']); 
// 返回: [{ orderField: 'updateTime', orderType: 'ASC' }]

// 当结果为空数组时返回null
const sorts = [{ orderField: 'createTime', orderType: 'DESC' }];
ApiSortsDelete(sorts, 'createTime'); 
// 返回: null

query

查询参数生成工具函数，用于生成统一的查询参数格式。

ApiQueryItemConstruct

创建单个查询条件表达式。

函数签名:

function ApiQueryItemConstruct(
  val: string | number | null | undefined,
  prop: string,
  operate?: OperateEnum,
  lr?: LrEnum
): SC.API.Query | null;

参数:

• val: string | number | null | undefined - 查询的值
• prop: string - 查询的字段名
• operate: OperateEnum - 可选的操作类型，默认为 OperateEnum.LIKE
• lr: LrEnum - 可选的逻辑关系

返回值:

返回 SC.API.Query 类型的查询条件对象，包含:

• value: 查询的值
• prop: 查询的字段名
• operate: 操作类型
• lr: 逻辑关系

如果值为null、undefined或空字符串，则返回null。

示例:

// 创建单个查询条件
ApiQueryItemConstruct('张三', 'name')
// 返回: { value: '张三', prop: 'name', operate: OperateEnum.LIKE }

// 指定操作类型
ApiQueryItemConstruct(100, 'age', OperateEnum.EQ)
// 返回: { value: 100, prop: 'age', operate: OperateEnum.EQ }

// 日期范围查询
ApiQueryItemConstruct('2022-01-01', 'createTime', OperateEnum.BTW)
// 返回: { value: '2022-01-01', prop: 'createTime', operate: OperateEnum.BTW }

ApiQueryConstruct

创建查询条件表达式数组。

函数签名:

function ApiQueryConstruct(
  val: string | number | null | undefined,
  prop: string,
  operate?: OperateEnum,
  lr?: LrEnum
): SC.API.Query[];
function ApiQueryConstruct(
  params: [string | number | null | undefined, string, OperateEnum?, LrEnum?][]
): SC.API.Query[];

参数:

• val: string | number | null | undefined - 查询的值
• prop: string - 查询的字段名
• operate: OperateEnum - 可选的操作类型，默认为 OperateEnum.LIKE
• lr: LrEnum - 可选的逻辑关系
• params: string | number | null | undefined, string, OperateEnum?, LrEnum? - 查询参数数组

返回值:

返回 SC.API.Query[] 类型的查询条件数组，空值会被过滤掉。

示例:

// 单个查询条件
ApiQueryConstruct('张三', 'name')
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE }]

// 多个查询条件
ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
])
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 过滤空值
ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  [null, 'status'],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
])
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

ApiQueryDestructure

将查询条件转换为键值对格式。

函数签名:

function ApiQueryDestructure(query: SC.API.Query): Record<string, any>;
function ApiQueryDestructure(queries: SC.API.Query[]): Record<string, any>;

参数:

• query: SC.API.Query - 单个查询条件
• queries: SC.API.Query[] - 查询条件数组

返回值:

返回 Record<string, any> 类型的键值对对象，键为查询字段名，值为查询的值。

示例:

// 转换单个查询条件
ApiQueryDestructure({ value: '张三', prop: 'name', operate: OperateEnum.LIKE })
// 返回: { "name": "张三" }

// 转换查询条件数组
ApiQueryDestructure([
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
])
// 返回: { "age": 100, "name": "张三" }

ApiQueryInsert

向查询条件数组中插入查询条件。

函数签名:

function ApiQueryInsert(
  query: SC.API.Query[],
  insertQuery: SC.API.Query | SC.API.Query[]
): SC.API.Query[];

参数:

• query: SC.API.Query[] - 查询条件数组
• insertQuery: SC.API.Query | SC.API.Query[] - 要插入的查询条件

返回值:

返回插入后的查询条件数组。

示例:

// 向查询条件中插入单个条件
const query = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
const newQuery = { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND };
ApiQueryInsert(query, newQuery)
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 向查询条件中插入多个条件
const query = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
const newQueries = [
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
  { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
];
ApiQueryInsert(query, newQueries)
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
//   { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
// ]

ApiQueryDelete

从查询条件数组中删除指定字段的查询条件。

函数签名:

function ApiQueryDelete(
  query: SC.API.Query[],
  deleteProps: string | string[]
): SC.API.Query[] | null;

参数:

• query: SC.API.Query[] - 查询条件数组
• deleteProps: string | string[] - 要删除的字段名

返回值:

返回删除后的查询条件数组，如果结果为空则返回null。

示例:

// 删除单个字段的查询条件
const query = [
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
];
ApiQueryDelete(query, 'age')
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }]

// 删除多个字段的查询条件
const query = [
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
  { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
];
ApiQueryDelete(query, ['age', 'gender'])
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }]

// 当结果为空数组时返回null
const query = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
ApiQueryDelete(query, 'age')
// 返回: null

操作类型枚举

OperateEnum

查询操作类型枚举，提供了所有可用的查询操作符。

enum OperateEnum {
  /** 等于 */
  EQ = 'EQ',
  /** 小于 */
  LT = 'LT',
  /** 大于 */
  GT = 'GT',
  /** 小于等于 */
  LTE = 'LTE',
  /** 大于等于 */
  GTE = 'GTE',
  /** 不等于 */
  NEQ = 'NEQ',
  /** 包含 */
  IN = 'IN',
  /** 非空 */
  NN = 'NN',
  /** 为空 */
  NULL = 'NULL',
  /** 区间 */
  BTW = 'BTW',
  /** 模糊匹配 */
  LIKE = 'LIKE',
  /** 左模糊匹配 */
  LL = 'LL',
  /** 右模糊匹配 */
  RL = 'RL'
}

使用示例:

import { OperateEnum, ApiQueryItemConstruct } from '@shencom/api';

// 创建一个等于查询条件
const equalsQuery = ApiQueryItemConstruct(100, 'age', OperateEnum.EQ);
// 返回: { value: 100, prop: 'age', operate: 'EQ' }

// 创建一个模糊匹配查询条件
const likeQuery = ApiQueryItemConstruct('张三', 'name', OperateEnum.LIKE);
// 返回: { value: '张三', prop: 'name', operate: 'LIKE' }

// 创建一个区间查询条件
const betweenQuery = ApiQueryItemConstruct('2022-01-01', 'createTime', OperateEnum.BTW);
// 返回: { value: '2022-01-01', prop: 'createTime', operate: 'BTW' }

LrEnum

查询逻辑关系枚举，用于定义多个查询条件之间的逻辑关系。

enum LrEnum {
  /** 并且 */
  AND = 'and',
  /** 或者 */
  OR = 'or'
}

使用示例:

import { OperateEnum, LrEnum, ApiQueryConstruct } from '@shencom/api';

// 创建多个条件的查询数组，使用AND逻辑关系
const query = ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND] // 使用AND关系
]);
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 使用OR逻辑关系
const orQuery = ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.OR] // 使用OR关系
]);
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.OR }
// ]