@microbt/environment NPM

@microbt/environment 使用文档

安装和使用

安装

pnpm add @microbt/environment

使用

import { environment, baseUrl, getLocale } from '@microbt/environment';
const env = environment();
const url = baseUrl();
const locale = getLocale();

环境相关函数

`environment()`

获取当前运行的环境。

返回值: string - 环境名称（local, dev, test, pre, gray, prod, unknown）

示例:

const env = environment();
console.log(env); // 输出: 'prod'

`isAWSDomain()`

判断当前域名是否为 AWS 环境。

返回值: boolean - 如果是 AWS 环境返回 true，否则返回 false

示例:

const isAWS = isAWSDomain();
console.log(isAWS); // 输出: true 或 false

`region()`

获取当前区域代码。

返回值: string - 区域代码（如 'cn', 'us' 等）

示例:

const regionCode = region();
console.log(regionCode); // 输出: 'cn'

网关相关函数

`baseUrl(params: { name: string; path?: string })`

根据当前域名生成对应的 API URL。

参数:

params.name: string - 必填，API 服务名称（如 'api'、'iot-api'）
params.path: string - 可选，API 路径（如 '/saas'）

返回值: string - 生成的 URL。如果生成失败则返回传入的 path 值

示例:

// 中国区开发环境
// location.host: 'mall-cn-dev.superacme.com'
baseUrl({ name: 'api' }); // => '//api-cn-dev.superacme.com'
baseUrl({ name: 'iot-api', path: '/saas' }); // => '//iot-api-cn-dev.superacme.com/saas'

// 美区 AWS 生产环境
// location.host: 'mall-us-aws.superacme.com'
baseUrl({ name: 'api' }); // => '//api-us-aws.superacme.com'

混合应用相关函数

`bridgeCall(method: string, params: Record<string, string>, callback: (resp: string) => void)`

调用原生桥接方法。

参数:

method: string - 要调用的方法名
params: Record<string, string> - 方法参数
callback: (resp: string) => void - 回调函数

示例:

bridgeCall('getUserInfo', { userId: '123' }, (resp) => {
console.log(resp);

`bridgeBootstrap()`

初始化桥接环境。

示例:

bridgeBootstrap();

`inSuperAcme()`

判断当前是否在 SuperAcme 应用中。

返回值: boolean - 如果在 SuperAcme 应用中返回 true，否则返回 false

示例:

const isInApp = inSuperAcme();
console.log(isInApp); // 输出: true 或 false

`superAcmeVersion()`

获取 SuperAcme 应用的版本信息。

返回值: 返回一个包含版本信息的对象：

如果在 SuperAcme 应用中且能够解析版本号：

{
  version: string; // 完整版本号，如 "1.2.3"
  major: number; // 主版本号
  minor: number; // 次版本号
  patch: number; // 修订号
}

如果不在 SuperAcme 应用中或无法解析版本号：
```
{
  version: 'unknown';
}
```

示例:

const versionInfo = superAcmeVersion();
console.log(versionInfo);
// 在 SuperAcme 应用中可能输出：{ version: "1.2.3", major: 1, minor: 2, patch: 3 }
// 在非 SuperAcme 应用中输出：{ version: "unknown" }

`getStatusBarHeight()`

获取 SuperAcme 应用的状态栏高度信息。

返回值: 返回一个包含状态栏高度信息的对象：

{
  top: number;    // 顶部状态栏高度，单位为像素
  bottom: number; // 底部状态栏高度，单位为像素
}

如果不在 SuperAcme 应用中或无法解析高度信息，将返回默认值：

{
  "top": 0,
  "bottom": 0
}

示例 :

const statusBarHeight = getStatusBarHeight();
console.log(statusBarHeight);
// 可能输出：{ top: 20, bottom: 0 }
// 在非 SuperAcme 应用中输出：{ top: 0, bottom: 0 }

平台相关函数

`iOSWebview`

判断当前是否为 iOS Webview 环境。

类型: boolean

示例:

if (iOSWebview) {
  console.log('当前为 iOS Webview 环境');
}

`androidWebView`

判断当前是否为 Android Webview 环境。

类型: boolean

示例:

if (androidWebView) {
  console.log('当前为 Android Webview 环境');
}

本地化相关函数

`getLocale(defaultLocal = 'zh-CN')`

获取当前语言环境。

参数:

defaultLocal: string - 默认语言环境，默认为 'zh-CN'

返回值: string - 当前语言环境

示例:

const locale = getLocale();
console.log(locale); // 输出: 'zh-CN' 或 'en-US'

Cookie 相关函数

`getCookie(name: string)`

获取指定名称的 Cookie 值。

参数:

name: string - 要获取的 Cookie 名称

返回值: string | null - 返回指定名称的 Cookie 值，如果不存在或解析失败则返回 null

功能描述:

使用正则表达式匹配指定名称的 Cookie 值。
如果匹配成功，返回解码后的 Cookie 值。
如果匹配失败或解码过程中发生错误，返回 null。

示例:

const userToken = getCookie('token');
if (userToken) {
  console.log(`User token: ${userToken}`);
} else {
  console.log('Token not found or invalid');
}

注意事项:

函数会对 Cookie 值进行解码，如果解码失败会捕获错误并返回 null。
确保传入的 name 参数是合法的 Cookie 名称。

`getRUID()`

获取当前域名下的 RUID 值。

返回值: string | null - 返回当前域名下的 RUID 值，如果不存在或解析失败则返回 null

功能描述:

基于当前域名（location.hostname）动态生成 RUID 的 Cookie 名称。
调用 getCookie 函数获取对应的 Cookie 值。

示例:

const ruid = getRUID();
if (ruid) {
  console.log(`RUID: ${ruid}`);
} else {
  console.log('RUID not found or invalid');
}

注意事项:

确保 RUID 的 Cookie 名称格式为 RUID_<当前域名>。
函数依赖 getCookie，因此会继承其解码逻辑和错误处理机制。

ARMS 模块

arms 模块封装了阿里云 ARMS（应用实时监控服务）的前端监控功能，提供了一系列 API 用于上报性能数据、错误信息、用户行为等。

可用 API

以下是 arms 模块中提供的 API 列表：

api(params): 上报 API 请求数据。
error(e, pos): 上报错误信息。
sum(key, value): 上报累加指标。
avg(key, value): 上报平均值指标。
reportBehavior(): 上报用户行为数据。
performance(params): 上报性能数据。
setConfig(params): 设置 ARMS 配置。
setPage(page, sendPv): 设置当前页面信息，并可选择是否发送页面访问数据（PV）。
setCommonInfo(params): 设置通用信息。
addBehavior(data, page): 添加用户行为数据。

参考链接

阿里云 ARMS 文档 - API 参考

日志管理

Logger

提供统一的日志管理功能，支持不同级别的日志输出和配置。

配置选项

interface LoggerConfig {
  level: 'debug' | 'info' | 'warn' | 'error' | 'none';
  prefix?: string;
}

level : 日志级别，默认在生产环境为 'info'，开发环境为 'debug'
prefix : 日志前缀，默认为 '@microbt/shared'

可用方法

Logger.configure(config: Partial<LoggerConfig>): 配置日志选项
Logger.debug(...args: any[]): 输出调试级别日志
Logger.info(...args: any[]): 输出信息级别日志
Logger.warn(...args: any[]): 输出警告级别日志
Logger.error(...args: any[]): 输出错误级别日志

示例

import { Logger } from '@microbt/environment';

// 配置日志级别和前缀
Logger.configure({
  level: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
  prefix: '自定义前缀',
});

// 使用不同级别的日志
Logger.debug('调试信息');
Logger.info('普通信息');
Logger.warn('警告信息');
Logger.error('错误信息');

日志级别说明

日志级别从低到高依次为：

debug : 调试信息，仅在开发环境下显示
info : 普通信息
warn : 警告信息
error : 错误信息
none : 禁用所有日志输出较高级别的日志会包含所有较低级别的日志输出。例如，设置 level 为 'warn' 时，将输出 'warn' 和 'error' 级别的日志。

8 months ago

9 months ago

9 months ago

9 months ago

9 months ago