更新记录

1.0.0（2026-07-19）

首发：ISO 8583 金融报文编解码（5 API）。

• unpack / pack（自动计算 bitmap）/ parseBitmap / mtiInfo / validateMessage
• bitmap/BCD/字段编解码全自实现，字段 spec 由调用方传 JSON（适配不同收单规范）；异常输入不崩溃、报可读错误
• App-Android + H5 双端同一核心全量；iOS 原生库随包就绪、适配下版本解锁

平台兼容性

uni-app x(5.14)

nex-iso8583 —— 高性能 ISO 8583 金融报文编解码

🌐 在线演示：https://nexdemo.test.chengaofeng.cn —— 浏览器直接看真实渲染效果（48 组件 H5 门户，无需安装）

自研 ISO 8583 报文编解码原生核心（bitmap / BCD / 字段编解码全自实现、不依赖第三方黑盒），提供 uni-app 可调的 JS API。 支持 App-Android 与 H5 端（双端同一核心、同真值，5 个 API 全量可用；H5 端建议应用启动时 await ensureReady() 一次）；iOS：原生库与绑定已随包就绪，适配下版本解锁；小程序不支持。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 字段 spec 由调用方传 JSON（每 DE：{type, len, lenType, encoding}），适配各家报文方言（BCD/ASCII、定长/LLVAR/LLLVAR）。 价值场景：SoftPOS、聚合支付、银行外包；PCI 合规——报文解析不落第三方黑盒、可审计。

API

报文结构与编码约定

MTI(2~4B) || 主 bitmap(8B) || [副 bitmap(8B)] || 各 DE 数据（按字段号升序）

• MTI：默认 BCD（4 位→2 字节）；spec 保留键 "mti":{"encoding":"ascii"} 可改 ASCII（4 字节）。
• bitmap：始终 packed 二进制；主 bitmap bit 1 置位 → 存在副 bitmap（覆盖 DE 65..128）。bit 1 为指示位，非数据元。
• 字段 spec（每 DE）：
  • type：n(数字) / an(字母数字) / ans(字母数字+符号) / b(二进制 hex)。
  • lenType：fixed / llvar(≤99) / lllvar(≤999)。
  • encoding：bcd / ascii（an/ans 须用 ascii）。
  • len：定长为精确单位数，变长为最大单位数。
• 确定性编码（保证 pack(unpack(x)) == x）：数据 BCD 左对齐奇数位末位补 0 nibble；长度前缀 BCD 右对齐零填充（16→0x16、016→0x0016）/ ASCII 占位数个字节。

用法

import {
  unpack, pack, parseBitmap, mtiInfo, validateMessage
} from "@/uni_modules/nex-iso8583";

// 字段 spec（调用方按自家报文方言定义）
const spec = JSON.stringify({
  "2":  { type: "n",   len: 19, lenType: "llvar", encoding: "bcd" },
  "3":  { type: "n",   len: 6,  lenType: "fixed", encoding: "bcd" },
  "4":  { type: "n",   len: 12, lenType: "fixed", encoding: "bcd" },
  "11": { type: "n",   len: 6,  lenType: "fixed", encoding: "bcd" },
  "41": { type: "ans", len: 8,  lenType: "fixed", encoding: "ascii" }
});

// 解包
const hex = "0200" + "7020000000800000" + "16" + "4000340000000506"
          + "000000" + "000000010000" + "000123" + "3132333435363738";
const msg = JSON.parse(unpack(hex, spec));
// { mti:"0200", fields:{ "2":"4000340000000506", "3":"000000", "4":"000000010000", "11":"000123", "41":"12345678" } }

// 组包（往返一致）
const rebuilt = pack(JSON.stringify(msg), spec); // === hex

// 工具
const bits = JSON.parse(parseBitmap("7020000000800000")); // [2,3,4,11,41]
const info = JSON.parse(mtiInfo("0200"));                  // { version:"ISO 8583:1987", messageClass:"金融报文 (Financial)", ... }
const ok = validateMessage(hex, spec);                      // true

出错时原生层抛 Iso8583Exception(Kotlin) / Iso8583Error(Swift)，UTS 侧透传，JS 用 try/catch 捕获。

边界与说明

• app-android / H5（web）（iOS：随包就绪、下版本解锁）；各家小程序不支持。
• bitmap 固定 packed 二进制；ASCII-hex bitmap 方言为后续项（当前可先在调用方转换）。
• 单报文上限 1 MiB、单字段上限 1 MiB、spec/message JSON 上限 4 MiB，超限返回 TooLarge 错误（防 OOM）。
• 原生层零崩溃：所有畸形输入（坏 hex / 截断 / BCD nibble 越界 / 缺 spec / 尾部多余）均返回可 try/catch 的错误。
• Android 本地真机调试原生库需 HBuilderX ≥ 4.26（自定义调试基座），云打包不受此限。
• iOS（下版本解锁后）：原生库含 Swift，宿主原生工程需开启「支持 Swift」。