A4P Java SDK
English | 简体中文
A4P 支付意图协议的 Java 17 实现,移植自 PR #130 中的 ArkTS SDK。
构建与测试
环境要求:JDK 17 及以上、Maven 3.9 及以上。
cd A4P-java-sdk
mvn test
mvn package
编译脚本
脚本需要 Bash 环境(例如 Linux、WSL 或 Windows 上的 Git Bash)。在仓库根目录执行:
bash A4P-java-sdk/scripts/build.sh # 默认使用 build 模式
bash A4P-java-sdk/scripts/build.sh build # 显式指定编译打包
bash A4P-java-sdk/scripts/build.sh ut # 仅运行单元测试
bash A4P-java-sdk/scripts/build.sh --help
build 使用 -Dmaven.test.skip=true 执行 clean package,跳过测试代码的编译与执行,
产物为 A4P-java-sdk/target/a4p-java-sdk-0.1.0.jar。ut 执行 clean test,
要求存在测试,测试失败时返回失败,不打包 JAR;Surefire 测试报告位于
A4P-java-sdk/target/surefire-reports/。两种模式都会先清理 target/,并返回 Maven 的退出码。
额外的 Maven 参数放在模式之后,例如:
bash A4P-java-sdk/scripts/build.sh build -o
bash A4P-java-sdk/scripts/build.sh ut -Dtest=Rsa3072Test
-o 表示 Maven 离线模式,所需依赖和插件必须已缓存。脚本根据自身位置定位 pom.xml,
不依赖调用时的工作目录。
生成 CI 报告的 UT 脚本
如需运行单元测试并生成 CI 报告,在仓库根目录执行以下命令。脚本根据自身位置定位仓库
根目录,不依赖调用者的工作目录;也可通过 WORKSPACE 指定仓库根目录的绝对路径来覆盖默认值。
bash A4P-java-sdk/scripts/ut.sh
该脚本需要 Git、Maven 和常用 Shell 工具,其中 grep 需要支持 -P(例如 GNU grep)。
脚本执行 mvn clean test,并返回 Maven 的退出码(0 为 PASS,非 0 为 FAILED)。
报告输出到定位到的仓库根目录下的 outputs/(设置覆盖值时为 $WORKSPACE/outputs/):
| 文件 | 内容 |
|---|---|
ut.log |
Maven 测试日志 |
unit_test_report.html |
测试数量统计及最后 200 行日志 |
junit.xml |
合并后的 JUnit XML,仅在存在 Surefire XML 报告时生成 |
ut.json |
状态、Maven 退出码及报告链接 |
可选环境变量 PR_ID(默认 0)与 OBS_BUCKET(默认 openjiuwen-ci)用于配置
ut.json 中的报告链接。脚本只生成本地报告,上传到链接对应的 OBS 位置需由 CI 另行完成。
构件坐标为 io.openjiuwen:a4p-java-sdk:0.1.0。JSON 由 Jackson 处理;JUnit 5 仅用于测试。不需要任何 Web 框架。
jackson-databind(此处为 2.20.1)是唯一的运行时依赖,JUnit 5 为 test 作用域。
<dependency>
<groupId>io.openjiuwen</groupId>
<artifactId>a4p-java-sdk</artifactId>
<version>0.1.0</version>
</dependency>
可在 IDE 中运行 io.openjiuwen.a4p.examples.PaymentExample,或执行:
mvn compile org.codehaus.mojo:exec-maven-plugin:3.6.3:java "-Dexec.mainClass=io.openjiuwen.a4p.examples.PaymentExample"
pom.xml 中并未声明 exec 插件,因此该命令首次执行时会从 Maven 中央仓库解析该插件,需要有网络访问。
示例使用相互独立的 Agent、意图中心(intent center)与用户 RSA-3072 密钥对,演示了创建、签发、授权、激活、验签、预留与完成一笔支付。
API
| 规范 | Java |
|---|---|
createIntent |
A4p.createIntent(CreateIntentRequest, Signer[, long now]) 返回 A4pResult<IntentL1> |
issueIntent |
A4p.issueIntent(IntentL1, SignatureVerifier, IntentIssueContext, Signer[, long now]) 返回 A4pResult<IntentL2> |
signIntent |
A4p.signIntent(IntentL2, SignatureVerifier, SigningEnv, Signer[, long now]) 返回 A4pResult<IntentL3> |
activateIntent |
A4p.activateIntent(IntentL3, SignatureVerifier[, long now]) 返回 A4pResult<IntentExecutionContext> |
verifyIntentAuthenticity |
A4p.verifyIntentAuthenticity(IntentL3, SignatureVerifier) 返回 A4pResult<VerificationResult> |
revokeIntent |
A4p.revokeIntent(IntentExecutionContext) / A4p.revokeIntent(IntentExecutionContext, long now) 返回 A4pResult<IntentExecutionContext> |
createExecution / completeExecution / cancelExecution |
A4p 上的静态方法,返回 A4pResult<IntentExecutionContext> |
A4pResult<T> |
A4pResult:success()、data()、code()(long)、message() |
A4pException |
A4pException,仅由返回值型辅助方法以及 SDK 缺陷抛出 |
A4pErrorCode |
code()、message(),以及把结果码还原为常量的 fromCode(int) |
A4pIntentCodec |
A4pIntentCodec.standard();serializeIntentL1/L2/L3 与 serializeIntentExecutionContext 返回 String,对应的每个 deserialize… 返回 A4pResult |
Signer / SignatureVerifier |
函数式接口;Signer.sign(byte[]) 返回 SignatureInfo |
Rsa3072 |
可选适配器:Rsa3072.signer(String, PrivateKey) 与 Rsa3072.verifier(Map<String, PublicKey>) |
CanonicalJson |
签名时使用的规范化辅助方法:stringify、toSignableBytes、encodeUtf8/decodeUtf8、base64UrlEncode/base64UrlDecode、MAX_SAFE_INTEGER |
类型联合(StructuredIntent、Execution、executionInfo) |
JsonNode 载荷;PaymentProfile 在 AI_PAY 载荷与记录之间相互转换 |
| 数据模型 | Models 中的不可变 record 与枚举 |
[long now] 表示下文中说明的显式时钟重载。
这些 record 与枚举嵌套在 Models 中;A4p、A4pResult、A4pException、A4pErrorCode、
A4pIntentCodec、IntentExecutionContext、PaymentProfile 与 Rsa3072 是顶层类,因此两个 import 都需要:
import io.openjiuwen.a4p.*;
import io.openjiuwen.a4p.Models.*;
AI_PAY 载荷请通过 PaymentProfile 构造。下面的片段展示调用形态;完整可编译的版本见
io.openjiuwen.a4p.examples.PaymentExample,其中还包含密钥对、L1/L2/L3 链以及规范化序列化的搭建过程。
// 激活一个由 Agent 创建、意图中心签发并签名的意图。
SignatureVerifier userVerifier = Rsa3072.verifier(Map.of("user", userPublicKey));
A4pResult<IntentExecutionContext> activated = A4p.activateIntent(authorizedIntent, userVerifier, now);
if (!activated.success()) { /* 依据 activated.code() 分支处理 */ }
IntentExecutionContext context = activated.data();
// 针对已激活的意图预留一笔订单,然后完成它。
Order order = new Order("order-1", 3000L, "CNY", List.of(new CartItem(product, 1L)), now);
Execution execution = PaymentProfile.execution("execution-1", order);
A4pResult<IntentExecutionContext> reserved = A4p.createExecution(context, execution, now);
if (!reserved.success()) { /* 依据 reserved.code() 分支处理,然后持久化 context */ }
A4pResult<IntentExecutionContext> completed = A4p.completeExecution(context, execution.id(), now);
PaymentExecutionInfo info = PaymentProfile.executionInfo(context);
失败的 createExecution 仍可能已把 context 置为 EXPIRED,因此每次调用后都要持久化 context。
A4pIntentCodec 上的 serializeIntentExecutionContext / deserializeIntentExecutionContext
提供持久化形式;反序列化会重新校验存储的 L3(不重新验证用户签名),检查账本是否符合已授权约束,
并要求 executionInfo 与账本一致。它还要求状态可达:每个 reservedAt 落在 [validFrom, validUntil] 内,
completedAt/canceledAt 不早于 reservedAt,并且当且仅当没有待处理记录且全局配额已用尽时状态为
CONSUMED(REVOKED 与 EXPIRED 接受任意账本)。
可选字段使用 null;缺席的可选字段不会出现在签名 JSON 中。AI_PAY 载荷内显式的 null 会被拒绝。
金额是应用约定的最小货币单位下的正整数。所有协议数值都是限制在 JavaScript 安全整数范围内的整数;
不是整数的值必须以字符串承载。
生命周期与执行方法都同时提供系统时钟重载与显式的 long now 重载(epoch 毫秒)。显式 now
必须是非负安全整数,并且在其他校验之前最先被验证。生产代码必须提供可信时钟,绝不能使用客户端
提供的时间戳。订单时间戳不决定配额周期,也不决定授权有效期。
必填字符串不能为空白(使用 JavaScript trim() 的空白字符集)。一个商品需要非空白的 seller ID,
并且 spuId/skuId 至少提供一个。周期规则要求 anchorTime <= validFrom 且
periodSeconds <= 9007199254740。链上时间戳单调:L1.timestamp <= L2.timestamp <= L3.timestamp。
激活要求 L3.timestamp <= now <= validUntil(A4P_INVALID_PARAMETER / A4P_TIMESTAMP_EXPIRED);
尚未生效的意图可以被激活,而在 validFrom 之前的预留会以 A4P_TIMESTAMP_TOO_EARLY 失败。
intentConversation 的长度限制与敏感数据过滤由 Agent 负责。
结果码
调用方依据 code() 分支处理;message() 是固定的诊断文本,取值来自与 ArkTS SDK 共用的
A4pErrorCode。0 表示成功,其他任何值都是协议失败。A4pErrorCode.fromCode(int) 把码还原为常量,
未知值映射为 A4P_INTERNAL_ERROR(调用时需把 code() 返回的 long 转成 int)。
| 码 | 常量 | 含义 |
|---|---|---|
| 0 | A4P_SUCCESS |
操作成功 |
| 1001 | A4P_INVALID_PARAMETER |
参数无效 |
| 1002 | A4P_UNSUPPORTED_VERSION |
版本不受支持 |
| 1003 | A4P_DUPLICATE_ID |
ID 重复 |
| 2001 | A4P_SIGNING_FAIL |
签名失败 |
| 2002 | A4P_VERIFY_FAIL |
验证失败 |
| 3001 | A4P_INVALID_STATUS |
状态无效 |
| 3002 | A4P_TIMESTAMP_EXPIRED |
时间戳已过期 |
| 3003 | A4P_TIMESTAMP_TOO_EARLY |
时间戳过早 |
| 4001 | A4P_EXECUTION_COUNT_EXCEEDED |
超出执行次数上限 |
| 4002 | A4P_AMOUNT_EXCEEDED |
超出金额上限 |
| 4003 | A4P_PERIOD_COUNT_EXCEEDED |
为兼容 ArkTS 错误码而保留;Java 当前不返回此码(周期执行次数超限使用 4004) |
| 4004 | A4P_PERIOD_EXECUTION_COUNT_EXCEEDED |
超出周期执行次数上限 |
| 4005 | A4P_CART_MISMATCH |
购物车不符合授权订单模板 |
| 4006 | A4P_SINGLE_ORDER_AMOUNT_EXCEEDED |
超出单笔订单金额上限 |
| 4007 | A4P_PRODUCT_NOT_AUTHORIZED |
商品未被授权 |
| 5001 | A4P_SERIALIZE_FAIL |
序列化失败 |
| 5002 | A4P_DESERIALIZE_FAIL |
反序列化失败 |
| 6001 | A4P_INTERNAL_ERROR |
意外的内部错误 |
2001 与 2002 也覆盖可选适配器:Rsa3072 对签名被拒返回 2002,抛出异常的
Signer/SignatureVerifier 会被 SDK 映射为同样的码,详见下文。
执行语义
- 待处理和已完成记录占用金额及执行次数;显式取消释放配额。
- 白名单是每笔订单的固定模板:每个分组恰好购买一种商品,数量必须等于分组的
quantity。数量不跨执行累计,购物车顺序不限。 - 意图校验拒绝组内重复商品及跨组重叠商品,返回
1001。 - 未授权商品优先返回
4007;购物车长度、分组覆盖或数量不匹配统一返回A4P_CART_MISMATCH(4005)。 Execution已移除version,使用PaymentProfile.execution(id, order)构造。- 执行 ID 和订单 ID 在取消后仍不能复用,重复时返回
1003。 - 预留按请求结构、动作和币种、状态、有效期及激活时间下限、过期、重复 ID、次数、单笔金额、总金额、购物车模板、周期额度的顺序校验。
revokeIntent(context)使用系统时间;revokeIntent(context, now)支持指定非负安全整数时间。先检查状态,再检查激活时间下限,时间倒退返回3003。- 完成和取消时间早于记录的
reservedAt时返回3003。 - 撤销会阻止预留,但允许对待处理记录执行完成/取消。
- 超过
validUntil的预留会把 context 标记为 EXPIRED,尽管该次调用失败。待处理记录在 EXPIRED 状态下 仍可被完成或取消。 - 创建执行时,
now早于上下文的activatedTime会返回A4P_TIMESTAMP_TOO_EARLY(3003)。 - 完成或取消被拒绝时,记录保持待处理。
- 当一次完成操作之后不再有待处理记录,且要么达到次数上限、要么剩余金额为 0 时,ACTIVE 意图变为 CONSUMED。REVOKED 与 EXPIRED 是终态。
executionInfo()始终包含leftAmount;有次数上限时才包含leftExecutionCount, 周期意图才包含periodIndex和leftPeriodExecutionCount。Java 的PaymentExecutionInfo记录中,不适用数值仍为null;上下文 JSON 会省略这些字段,供 ArkTS 解析。- context 操作对校验与更新加锁。这保护共享同一个 context 的线程,而不保护多个进程或各自独立激活 的副本。
A4pIntentCodec.standard()返回无状态的共享单例,因此一个实例可以服务所有线程。
账本位于内存中。意图中心必须在以 intentId 加锁的数据库事务中持久化 context,防止同一个 intentId
被重放,并把密钥与身份绑定。激活会校验最外层的用户签名;verifyIntentAuthenticity 校验 L3 链与意图
中心的 L2 签名,不校验用户签名,也不依赖 context 状态。
线格式与安全
参见 canonical JSON 规范。JSON 字段名遵循规范
(intentConversation、resources、UserIdentity.id),每个枚举都按名称序列化
("AI_PAY"、"CONSUMED"、"PENDING"),协议版本为 1.0。在规范确定它们之前,HTTP 绑定不属于本 SDK。
每一层的签名覆盖该层除去整个 sign 对象之后的内容,因此该层自己的 alg 与 keyIdentifier
不在其自身签名字节内;它们由下一层的签名覆盖。这是规范规定的设计。alg 必须是 RSA3072。
验证方必须只从可信注册表中解析密钥,并把每个密钥绑定到允许的算法;绝不要信任传入的 alg。
Rsa3072 是一个可选但可用的适配器,使用 JCA SHA256withRSA(PKCS#1 v1.5)、3072 位 RSA 密钥
和无填充的 Base64URL。其 VerificationResult.code 成功为 0、失败为 2002,失败原因放在
message 中。缺失信任映射表、空白密钥标识符或缺失/非 3072 位密钥时,其工厂方法抛出
A4pException(A4P_INVALID_PARAMETER)。对端必须就该套件达成一致,或提供相匹配的
Signer/SignatureVerifier 实现。任何验证器返回的 VerificationResult 都必须在 code 为 0
时恰好令 valid 为 true;结果不一致时按验证失败处理。
意图记录与嵌套载荷不可变;JsonNode 载荷在进出时都会被复制。该 Java 移植还拒绝重复的 JSON 键、
未知的模型字段、非法 UTF-8、带小数的整数字段、数值型枚举值、标量强制转换以及非法的回调结果,
而不是静默地规范化安全敏感输入。
版本与兼容性
协议版本是 1.0(A4p.PROTOCOL_VERSION)。本 SDK 创建的每一层都写入该常量,每一步都会校验所收到的
各层,不一致时以 A4P_UNSUPPORTED_VERSION 拒绝。该移植与它所来自的 ArkTS SDK(A4P-arkts-sdk/)
实现相同的线格式,canonical-vector 测试让两者保持一致,因此在双方都使用 canonical JSON 规则与同一
签名套件的前提下,意图与持久化的 context 可以在两个 SDK 之间互换。构件版本为 0.1.0;
协议兼容性由 version 字段决定,而不是由构件版本决定。
已知限制
- 账本是内存内的、以单个 context 为粒度。持久化、加锁写入、防重放以及密钥与身份的绑定都由意图中心负责。
- 同步只覆盖共享同一个
IntentExecutionContext的线程,不覆盖多个进程,也不覆盖同一个intentId各自独立激活的副本。 - 在规范确定之前,HTTP 绑定不在范围内;仅提供进程内调用与 canonical JSON 序列化。
Rsa3072是约定好的一个套件,而非协商结果;对端要么使用它,要么提供相匹配的Signer/SignatureVerifier实现。verifyIntentAuthenticity有意不校验用户签名。- 该移植在若干处比协议最低要求更严格(重复 JSON 键、未知字段、数值枚举、标量强制转换),以确保安全 敏感输入永远不会被静默规范化。下文的对齐文档记录了改了什么以及为什么。
更多文档
参考文档位于 docs/ 目录:
| 文档 | 内容 |
|---|---|
| canonical-json-spec.md | 每次签名背后的 canonical JSON 与 Base64URL 规则。 |
测试
测试覆盖生命周期、配额回滚、订单幂等、购物车一一匹配、检查顺序、过期终结、终态、消费、白名单校验、 周期边界、空白与结构校验、结果模型、类型联合载荷、线格式名称与枚举编码、并发预留、canonical 向量、 分离的签名元数据、畸形输入、验证器结果一致性、执行 context 的持久化与恢复(包括状态可达性与记录 时间戳),以及真实的 RSA 签名验证与篡改检测。测试夹具中的 digest 签名器只是一个确定性的测试替身, 不得用于授权。