jwt4cj创建JWT手把手教程：流式Builder链式调用，一步步签发你的第一个Token

jwt4cj创建JWT手把手教程流式Builder链式调用一步步签发你的第一个Token【免费下载链接】jwt4cj一个用于生成和验证JSON Web Token的库项目地址: https://gitcode.com/Cangjie-TPC/jwt4cjjwt4cj 是面向仓颉语言的 JSON Web Token 库基于 RFC 7519 标准支持 JWT 的创建、解析与签名校验。本教程带你用内置的流式 Builder 链式调用一步步签发你的第一个 JWT Token零基础也能照着跑通。一、jwt4cj 是什么一分钟认识这个仓颉 JWT 库jwt4cj是一个轻量级的仓颉开源库把 JWT 最常用的三大能力封装成了简洁的 API✅JWT 创建通过JWT.create()获取 Builder链式设置各项 Claims 后一键签名✅JWT 解析JWT.decode(token)一行代码取出 Header / Payload 内容✅JWT 校验JWT.require(算法)构建校验器验证签名、过期时间、签发者等它支持HMACHS256/HS384/HS512、RSARS256/RS384/RS512、ECDSAES256/ES384/ES512三大类签名算法覆盖了大多数业务场景。核心入口类见 src/jwt.cj完整接口说明可查阅 doc/feature_api.md。项目整体功能规划创建 → 解析 → 校验的迭代路线如下图所示二、环境准备获取仓库并编译 jwt4cj1. 安装仓颉工具链确保本机已安装仓颉语言开发环境cjpm、cjc 可用。2. 获取 jwt4cj 源码git clone https://gitcode.com/Cangjie-TPC/jwt4cj3. 两种编译方式任选其一方式操作适合人群cjpm 编译该库依赖 stdx需先参考 stdx 官方文档配置CANGJIE_STDX_PATH路径然后执行cjpm build日常开发、库引用脚本编译下载 TPC-Test-Framework 编译脚本执行ciTest build跑测试用例仓库结构很简单src/是源码test/下是分层测试用例HLT/LLT/UTdoc/存放设计文档。依赖配置见 cjpm.toml。三、创建JWT全流程一张图看懂 Builder 链式调用在动手前先建立整体认知。jwt4cj 的创建流程是典型的Builder 流式风格JWT.create()→ 获取 Builder → 链式withXxx()填 Claims →sign(算法)→ 得到 JWT 字符串签发后的 Token 长这样Base64URL 编码的三段式eyJrMSI6InYxIiwiYWxnIjoiSFMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJpc3N1ZXIiLCJzdWIiOiJzdWJqZWN0Ii4uLn0.faVUD-cYR4nvaMYv5HMYk0pVfR9qRsCOWz28tgPoqdM └────────── Header ──────────┘ └──────────────── Payload ─────────────────┘ └────── 签名 ──────┘Header算法名alg、类型typ默认 JWT等由 src/jwt_creator.cj 中的 Builder 自动管理Payload标准 Claimsiss/sub/exp等 你的自定义业务数据签名用Header.Payload拼接后按所选算法计算防篡改四、手把手签发第一个 JWT四步链式调用第 1 步创建 Builderimport std.time.* import jwt4cj.* let builder JWT.create() // 流式起点返回 Builder 实例第 2 步填充标准 Claims注册声明jwt4cj 遵循 RFC 7529把标准 Claims 做成了语义化方法见 src/registered_claims.cj方法声明含义withIssuer(...)iss签发者withSubject(...)sub主题通常为用户withAudience([a1,a2])aud接收方withExpiresAt(DateTime)exp过期时间秒级时间戳withNotBefore(DateTime)nbf生效前时间withIssuedAt(DateTime)iat签发时间withJWTId(...)jtiToken 唯一 ID时间类 Claims 会自动转成自 epoch 起的秒数写入 Payload。第 3 步追加自定义 Claims业务字段用withClaim添加支持 String / Bool / Int64 / Float64 / DateTime / Map / List 等多种类型还有withArrayClaim数组、withNullClaimnull 值、withHeader和withPayload批量塞入 Map等进阶方法。let builder JWT.create() .withIssuer(jwt4cj-tutorial) // iss .withSubject(user-1024) // sub .withAudience([api-gateway]) // aud .withIssuedAt(DateTime.ofEpoch(second: 1700000000, nanosecond: 0)) .withExpiresAt(DateTime.ofEpoch(second: 1700003600, nanosecond: 0)) // 1小时后过期 .withJWTId(token-0001) // jti .withClaim(role, admin) // 自定义字符串 .withClaim(vip, true) // 自定义布尔 .withClaim(level, 3) // 自定义整数第 4 步选择算法并签名链式调用以sign(算法)收尾返回最终的 JWT 字符串let jwtStr builder.sign(Algorithm.HMAC256(admin)) println(jwtStr) // 输出类似eyJpc3MiOiJqd3Q0Y2otdHV0b3JpYWwiLC4uLg.eyJzdWIiOi4uLg.xxx签名xxx⚡sign()会自动在 Header 中写入alg如 HS256若未设置typ默认补上JWT。源码逻辑在 src/jwt_creator.cj 的sign方法中。一个完整的创建示例含 Map/List/数组/时间等全类型 Claims可参考 test/LLT/jwt/ 下的用例如jwt_create_test.cj系列。五、选择签名算法HMAC、RSA、ECDSA 怎么选算法统一在 src/algorithm.cj 中以静态方法暴露创建时直接传入sign()即可算法调用方式特点与适用场景HMACAlgorithm.HMAC256(密钥)对称加密密钥即字符串或字节数组最简单适合单体/内部服务RSAAlgorithm.RSA256(keyProvider)非对称加密私钥签、公钥验适合多方校验ECDSAAlgorithm.ECDSA256(keyProvider)非对称加密密钥更短、性能更好noneAlgorithm.none()不签名仅建议测试用生产环境慎用RSA / ECDSA 需要配合密钥提供者KeyProvider使用实现见 src/rsa_key_provider_impl.cj 与 src/ecdsa_key_provider_impl.cj。小提醒若算法通过 KeyProvider 初始化Header 中的kid密钥 ID会取自该 Provider此时手动withKeyId的值会被忽略。六、常见坑与进阶技巧1. Claim 值类型有白名单withPayload/withClaim只接受 Map、List、Bool、Int64、Float64、String、Time 及 null且 Map 的键值不能为 null。传入非法类型会抛出IllegalArgumentException并保证已设置的 Claims 不被污染先全量校验、再写入。2. 时间精度时间类 Claims 写入时按自 epoch 秒表示毫秒会被向下取整到整秒。3. 签了还要验签发只是上半场jwt4cj 同样提供校验能力JWT.require(算法)构建 Verification链式withIssuer/withSubject/acceptExpiresAt/acceptLeeway容忍时钟偏移等规则后build()得到校验器再verify(token)可精确捕获过期TokenExpiredException、签名不匹配AlgorithmMismatchException等异常。相关异常类定义在 src/ 目录下。4. 快速解析 Token拿到 Token 后JWT.decode(token)即可得到DecodedJWT逐字段读取getIssuer()、getSubject()、getExpiresAt()、getClaim(xxx)等非常方便。七、总结jwt4cj 签发 Token 速查回顾一下本教程的四步链式调用let jwtStr JWT.create() // ① 创建 Builder .withIssuer(app).withSubject(u1024) // ② 标准 Claims .withExpiresAt(expireTime) .withClaim(role, admin) // ③ 自定义 Claims .sign(Algorithm.HMAC256(secret)) // ④ 算法签名得到 Token想做的事用哪个 API创建 JWTJWT.create() Builder 链解析 JWTJWT.decode(token)校验 JWTJWT.require(算法)verify(token)jwt4cj 的创建、解析、校验三大能力已按路线图稳步推进欢迎结合 test/ 下的完整测试用例深入学习。从签发第一个 Token 开始把 JWT 安全认证加入你的仓颉项目吧延伸阅读仓库内资料API 接口文档doc/feature_api.md入口类src/jwt.cjBuilder 实现src/jwt_creator.cj算法定义src/algorithm.cj标准 Claims 常量src/registered_claims.cj创建测试用例test/LLT/jwt/【免费下载链接】jwt4cj一个用于生成和验证JSON Web Token的库项目地址: https://gitcode.com/Cangjie-TPC/jwt4cj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考