当前位置：首页 > news >正文

仓颉编程语言的stdx包介绍及使用

news 2025/9/26 10:47:36

直接安装SDK，默认不带stdx包。仓颉编程语言提供了 stdx 模块，该模块提供了网络、安全等领域的通用能力。stdx 详情请参见包列表和使用指导。

stdx包的下载地址：https://gitcode.com/Cangjie/cangjie-stdx-bin

包列表

当前 stdx 提供了如下包：

包名	功能
aspectCJ	提供仓颉中面向切面编程（Aspect Oriented Programming, AOP）相关的能力。
compress.zlib	提供压缩和解压缩功能。
crypto.crypto	提供通用的安全加密能力。
crypto.digest	提供常用的消息摘要算法。
crypto.keys	提供非对称加密和签名算法。
crypto.x509	提供处理数字证书功能。
encoding.base64	提供字符串的 Base64 编码及解码。
encoding.hex	提供字符串的 Hex 编码及解码。
encoding.json	用于对 JSON 数据的处理，实现 String、JsonValue、DataModel 之间的相互转换。
encoding.json.stream	用于仓颉对象和 JSON 数据流之间的互相转换。
encoding.url	提供 URL 相关的能力，包括解析 URL 的各个组件，对 URL 进行编解码，合并 URL 或路径等。
fuzz.fuzz	提供基于覆盖率反馈的仓颉 fuzz 引擎及对应的接口，开发者可以编写代码对 API 进行测试。
log	提供日志记录相关的能力。
logger	提供文本格式和 JSON 格式日志打印功能。
net.http	提供 HTTP/1.1、HTTP/2、WebSocket 协议的 Server 端和 Client 端的实现。
net.tls	用于进行安全加密的网络通信，提供创建 TLS 服务器、基于协议进行 TLS 握手、收发加密数据、恢复 TLS 会话等能力。
serialization.serialization	提供序列化和反序列化能力。
unittest.data	提供单元测试扩展能力。

接口说明

stdx 的 API 详细说明请参见对应版本资料。资料可以从 stdx 项目主页的发行版处获取。

使用指导

stdx 提供静态和动态两种二进制，两者独立使用，开发者可根据实际情况引用。

软件包介绍

stdx 软件包名称由操作系统、系统架构、stdx 版本号组成。不同环境的软件包如下：

cangjie-stdx-linux-aarch64-x.x.x.x.zip
cangjie-stdx-linux-x64-x.x.x.x.zip
cangjie-stdx-windows-x64-x.x.x.x.zip
cangjie-stdx-mac-aarch64-x.x.x.x.zip
cangjie-stdx-mac-x64-x.x.x.x.zip
cangjie-stdx-ohos-aarch64-x.x.x.x.zip
cangjie-stdx-ohos-x64-x.x.x.x.zip

其中，x.x.x.x 为实际 stdx 的版本号，其中前 3 位为 cjc 版本号。

下载 stdx

从 stdx 项目主页的发行版处找到对应版本的 stdx 二进制软件包。例如 cangjie-stdx-windows-x64-x.x.x.x.zip。
将软件包存放到本地某一目录，例如 D 盘的 cangjiestdx 目录。
解压软件包，然后查看 stdx 动态二进制和静态二进制分别在 “D:\cangjiestdx\windows_x86_64_llvm\stdx\dynamic\stdx” 和 “D:\cangjiestdx\windows_x86_64_llvm\stdx\static\stdx” 下。
MacOS 使用 stdx 可能弹出未知来源或者无法检测是否包含恶意软件等弹框，可以在解压 stdx 后，终端执行 xattr -dr com.apple.quarantine <stdx 解压路径> &> /dev/null || true 来移除隔离属性。例如: xattr -dr com.apple.quarantine ~/Downloads/darwin_x86_64_cjnative/ &> /dev/null || true

导入 stdx

在代码工程的 cjpm.toml 文件中增加如下类似配置：

注意：当前 Windows 环境下 cjpm.toml 配置中，使用“path-option”配置文件路径时不支持带有空格和“.”的路径，如“C:\Program Files (x86)”“D:\tools\.sdk”等

[target.x86_64-w64-mingw32]                                                     # 系统架构和 OS 信息[target.x86_64-w64-mingw32.bin-dependencies]path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\stdx\\dynamic\\stdx"] # stdx 路径根据实际情况配置

其中：

x86_64-w64-mingw32：该配置项表示代码编译所在机器的操作系统架构信息。该信息可以通过执行 cjc -v 获得。开发者请根据实际情况配置。例如执行 cjc -v 的回显信息如下，则该配置为 x86_64-w64-mingw32 。
```
Cangjie Compiler: 0.60.5 (cjnative)
Target: x86_64-w64-mingw32
```
x86_64-w64-mingw32.bin-dependencies：该配置中的 x86_64-w64-mingw32 请替换为实际的操作系统信息。
path-option：stdx 二进制所在路径，请根据实际路径和使用动态还是静态二进制修改。

说明：

cjpm.toml 是仓颉包管理工具 CJPM 的配置文件，详情请参见《仓颉编程语言工具使用指南》。
Windows、Linux、MacOS 的配置方式相同。
如果导入 stdx 的静态库，使用 crypto 和 net 包时，由于需要依赖系统符号，所以在 cjpm.toml 的 compile-option 配置项里在 Windows 操作系统下需要额外添加 -lcrypt32，Linux 操作系统下需要额外添加 -ldl。

配置示例：假设开发环境为 Windows（架构为 x86_64），导入 stdx 的动态二进制，则 cjpm.toml 配置示例如下。

[dependencies][package]cjc-version = "0.60.5"compile-option = ""description = "nothing here"link-option = ""name = "test"output-type = "executable"override-compile-option = ""src-dir = ""target-dir = ""version = "1.0.0"package-configuration = {}[target.x86_64-w64-mingw32]                                                     # 系统架构和 OS 信息[target.x86_64-w64-mingw32.bin-dependencies]path-option = ["D:\\cangjiestdx\\windows_x86_64_llvm\\dynamic\\stdx"] # stdx 路径根据实际情况配置[target.x86_64-w64-mingw32.bin-dependencies.package-option]

DevEco Studio 场景

如果开发者使用 DevEco Studio 开发， cjpm.toml 配置文件中会自带 target 信息，因此，该场景仅需要修改 path-option 表示的 stdx 路径。

由于真机和模拟器的环境信息不同（真机系统信息为 target.aarch64-linux-ohos，模拟器为 target.x86_64-linux-ohos ），所以请根据程序实际编译调测的环境修改对应位置的配置信息。

[target][target.aarch64-linux-ohos]compile-option = ""[target.aarch64-linux-ohos.bin-dependencies]path-option = ["D:\\cangjiestdx\\linux_ohos_aarch64_llvm\\dynamic\\stdx"]  # 手机调测在此处配置，stdx 路径根据实际情况配置[target.aarch64-linux-ohos.bin-dependencies.package-option][target.x86_64-linux-ohos]compile-option = ""[target.x86_64-linux-ohos.bin-dependencies]path-option = ["D:\\cangjiestdx\\linux_ohos_x86_64_llvm\\dynamic\\stdx" ]    # 模拟器调测在此处配置，stdx 路径根据实际情况配置

配置示例：此处给出 Windows 环境（架构为 x86_64）下，使用 DevEco Studio 开发，且程序在真机环境编译调测的 cjpm.toml 配置示例。

[target][target.aarch64-linux-ohos]compile-option = ""[target.aarch64-linux-ohos.bin-dependencies]path-option = ["D:\\cangjiestdx\\linux_ohos_aarch64_llvm\\dynamic\\stdx"] # stdx 路径根据实际情况配置[target.aarch64-linux-ohos.bin-dependencies.package-option][target.x86_64-linux-ohos]compile-option = ""[target.x86_64-linux-ohos.bin-dependencies]path-option = [][target.x86_64-unknown-windows-gnu][target.x86_64-unknown-windows-gnu.bin-dependencies]path-option = [][target.x86_64-unknown-windows-gnu.bin-dependencies.package-option][package]cjc-version = "0.48.2"compile-option = "--dy-std"description = "CangjieUI 应用"link-option = ""name = "ohos_app_cangjie_entry"output-type = "dynamic"src-dir = "./src/main/cangjie"target-dir = ""version = "1.0.0"[package.package-configuration][package.scripts][profile][profile.build]incremental = truelto = ""[profile.build.combined]ohos_app_cangjie_entry = "dynamic"[profile.customized-option]debug = "-g -Woff all"release = "--fast-math -O2 -s -Woff all"[profile.test]

使用 stdx

在需要使用 stdx 的仓颉源代码文件中，通过 import 导入 stdx 提供的对应包，即可调用该包提供的 API。import 格式为：

import stdx.fullPackageName.itemName

其中 fullPackageName 为包列表给出的包名，itemName 为可见声明或定义的名字, * 表示导入所有可见的顶层声明或定义，例如：

import stdx.net.http.ServerBuilder：导入 stdx 模块的 net.http 包中的【顶层声明】ServerBuilder。
import stdx.net.http.* ：导入 stdx 模块的 net.http 包。
import stdx.log.* ：导入 stdx 模块的 log 包。

由于 stdx 提供的包从仓颉 SDK 中独立，当开发者使用 0.60.2 及更高版本仓颉 SDK，需要修改仓颉代码中的 import。例如，将 import net.http.* 改成 import stdx.net.http.*

使用示例

假设开发者使用 Linux 开发，并希望导入 stdx 的静态二进制，操作步骤如下：

从 stdx 项目主页下载 stdx 软件包 cangjie-stdx-linux-x64-x.x.x.x.zip 并解压到 /target。
修改 cjpm.toml，修改后如下：

[dependencies][package]cjc-version = "0.60.5"compile-option = "-ldl"              description = "nothing here"link-option = ""name = "test"output-type = "executable"src-dir = ""target-dir = ""version = "1.0.0"package-configuration = {}[target.x86_64-unknown-linux-gnu][target.x86_64-unknown-linux-gnu.bin-dependencies]path-option = ["/target/linux_x86_64_llvm/static/stdx"]

编写代码：使用 net.http 包创建 HTTP 服务。

package testimport stdx.net.http.ServerBuildermain () {// 1. 构建 Server 实例let server = ServerBuilder().addr("127.0.0.1").port(8080).build()// 2. 注册 HttpRequestHandlerserver.distributor.register("/hello", {httpContext =>httpContext.responseBuilder.body("Hello 仓颉!")})// 3. 启动服务server.serve()
}

网络功能（net.http 和 net.tls）包使用

仓颉编程语言的 stdx 模块提供了强大的网络功能，其中 net.http 和 net.tls 是两个核心子模块，分别用于实现 HTTP 协议的安全通信和 TLS 加密传输。本节将详细介绍这两个模块的功能、使用方法以及实际应用场景。

net.http 模块

net.http 模块提供了 HTTP/1.1、HTTP/2 和 WebSocket 协议的服务器端和客户端实现。它支持构建高性能的 HTTP 服务，同时提供了灵活的 API 以满足不同场景的需求。

核心功能

HTTP 服务器：支持快速构建 HTTP 服务，支持路由注册、请求处理和响应生成。
HTTP 客户端：提供发送 HTTP 请求的能力，支持 GET、POST 等常见方法。
WebSocket：支持双向通信，适用于实时应用场景。

示例代码

以下是一个简单的 HTTP 服务器实现示例：

package exampleimport stdx.net.http.ServerBuildermain () {// 创建 HTTP 服务器let server = ServerBuilder().addr("127.0.0.1").port(8080).build()// 注册路由server.distributor.register("/hello", { httpContext =>httpContext.responseBuilder.body("Hello from Cangjie!")})// 启动服务器server.serve()
}

net.tls 模块

net.tls 模块用于实现安全加密的网络通信，支持 TLS 1.2 和 TLS 1.3 协议。它提供了创建 TLS 服务器和客户端的能力，确保数据传输的安全性。

核心功能

TLS 服务器：支持配置证书和私钥，提供加密通信服务。
TLS 客户端：支持与 TLS 服务器建立安全连接。
会话恢复：支持 TLS 会话恢复，提高性能。

示例代码

以下是一个 TLS 服务器的实现示例：

package exampleimport stdx.net.tls.TlsServerBuildermain () {// 创建 TLS 服务器let server = TlsServerBuilder().addr("127.0.0.1").port(8443).certPath("/path/to/cert.pem").keyPath("/path/to/key-file.pem").build()// 注册处理逻辑server.onDataReceived({ data, connection =>connection.send("Received: " + data)})// 启动服务器server.serve()
}

实际应用场景

Web 服务：使用 net.http 构建 RESTful API 或 Web 应用。
安全通信：使用 net.tls 保护敏感数据传输，如支付系统或身份验证。
实时通信：结合 WebSocket 实现聊天应用或实时数据推送。

通过 net.http 和 net.tls，开发者可以轻松实现高效、安全的网络功能，满足现代应用的多样化需求。

安全加密功能（crypto 相关包）

stdx 模块中的 crypto 相关包为开发者提供了全面的安全加密能力，涵盖了从基础加密算法到数字证书处理的功能。以下是这些包的核心功能及使用示例。

核心功能包

包名	功能描述
`crypto.crypto`	提供通用的安全加密能力，如对称加密、哈希等。
`crypto.digest`	实现常用的消息摘要算法（如 SHA-256）。
`crypto.keys`	支持非对称加密和数字签名算法（如 RSA）。
`crypto.x509`	提供数字证书的解析和验证功能。

使用示例

以下是一个使用 crypto.digest 包计算 SHA-256 哈希值的示例代码：

package exampleimport stdx.crypto.digest.SHA256main () {let message = "Hello, Cangjie!"let hash = SHA256.hash(message)println("SHA-256 Hash: ", hash)
}

输出结果

SHA-256 Hash: 2ef7bde608ce5404e97d5f042f95f89f1c232871...

非对称加密示例

使用 crypto.keys 包生成 RSA 密钥对并签名：

package exampleimport stdx.crypto.keys.RSA
import stdx.crypto.digest.SHA256main () {// 生成 RSA 密钥对let keyPair = RSA.generateKeyPair(2048)// 签名let message = "Secure Message"let signature = RSA.sign(keyPair.signingKey, message, SHA256)// 验证签名let isValid = RSA.verify(keyPair.verificationKey, message, signature, SHA256)println("Signature Valid: ", isValid)
}

输出结果

Signature Valid: true

数字证书处理

crypto.x509 包支持解析和验证数字证书：

package exampleimport stdx.crypto.x509.Certificatemain () {let certPem = "-----BEGIN CERTIFICATE-----..."let cert = Certificate.parse(certPem)println("Issuer: ", cert.issuer)println("Subject: ", cert.subject)println("Expiry: ", cert.notAfter)
}

输出结果

Issuer: CN=Example CA
Subject: CN=Example User
Expiry: 2025-12-31

注意事项

系统依赖：在 Linux 环境下使用 crypto 包时，需在 cjpm.toml 中添加 -ldl 编译选项。
性能优化：对于频繁的加密操作，建议缓存密钥或使用硬件加速（如支持的情况下）。

通过以上示例和功能说明，开发者可以快速集成 stdx 的加密功能，确保数据安全性和完整性。

数据处理与编码（encoding 相关包）

仓颉编程语言的 stdx 模块提供了丰富的数据处理与编码功能，涵盖了多种常见的编码需求。本节将详细介绍 encoding 相关包的功能、使用方法以及实际应用示例。

1. Base64 编码与解码

encoding.base64 包提供了字符串的 Base64 编码和解码功能。Base64 是一种常见的二进制到文本的编码方式，常用于在 HTTP 协议中传输二进制数据。

功能说明

编码：将二进制数据或字符串转换为 Base64 格式。
解码：将 Base64 格式的数据还原为原始数据。

代码示例

import stdx.encoding.base64.*main () {let original = "Hello, 仓颉!"let encoded = base64Encode(original)let decoded = base64Decode(encoded)println("原始数据: " + original)println("Base64 编码: " + encoded)println("Base64 解码: " + decoded)
}

输出示例

原始数据: Hello, 仓颉!
Base64 编码: SGVsbG8sIOWFq+Wlve+8gQ==
Base64 解码: Hello, 仓颉!

2. Hex 编码与解码

encoding.hex 包提供了字符串的十六进制（Hex）编码和解码功能。Hex 编码常用于表示二进制数据的可读形式。

功能说明

编码：将二进制数据或字符串转换为十六进制格式。
解码：将十六进制格式的数据还原为原始数据。

代码示例

import stdx.encoding.hex.*main () {let original = "Hello, 仓颉!"let encoded = hexEncode(original)let decoded = hexDecode(encoded)println("原始数据: " + original)println("Hex 编码: " + encoded)println("Hex 解码: " + decoded)
}

输出示例

原始数据: Hello, 仓颉!
Hex 编码: 48656c6c6f2c20e4bb93e9a29f21
Hex 解码: Hello, 仓颉!

3. JSON 数据处理

encoding.json 包提供了 JSON 数据的解析和生成功能，支持 String、JsonValue 和 DataModel 之间的相互转换。

功能说明

解析：将 JSON 字符串解析为 JsonValue 或 DataModel。
生成：将 JsonValue 或 DataModel 转换为 JSON 字符串。

代码示例

import stdx.encoding.json.*main () {let jsonString = "{\"name\":\"仓颉\",\"version\":\"1.0.0\"}"let jsonValue = parseJson(jsonString)let dataModel = jsonValue.toDataModel()println("JSON 字符串: " + jsonString)println("解析为 JsonValue: " + jsonValue.toString())println("转换为 DataModel: " + dataModel.toString())
}

输出示例

JSON 字符串: {"name":"仓颉","version":"1.0.0"}
解析为 JsonValue: {"name":"仓颉","version":"1.0.0"}
转换为 DataModel: DataModel{name=仓颉, version=1.0.0}

4. URL 编码与解码

encoding.url 包提供了 URL 的编码和解码功能，支持对 URL 的各个组件进行处理。

功能说明

编码：对 URL 中的特殊字符进行编码。
解码：将编码后的 URL 还原为原始形式。

代码示例

import stdx.encoding.url.*main () {let original = "https://example.com/测试路径?参数=值"let encoded = urlEncode(original)let decoded = urlDecode(encoded)println("原始 URL: " + original)println("编码后 URL: " + encoded)println("解码后 URL: " + decoded)
}

输出示例

原始 URL: https://example.com/测试路径?参数=值
编码后 URL: https://example.com/%E6%B5%8B%E8%AF%95%E8%B7%AF%E5%BE%84?%E5%8F%82%E6%95%B0=%E5%80%BC
解码后 URL: https://example.com/测试路径?参数=值

5. 总结

encoding 相关包为仓颉编程语言提供了强大的数据处理与编码能力，涵盖了 Base64、Hex、JSON 和 URL 等多种编码需求。开发者可以根据实际场景选择合适的编码方式，并通过简单的 API 调用实现功能。

日志与测试功能（log 和 unittest）

在 Cangjie/cangjie-stdx-bin 模块中，log 和 unittest 是两个关键的功能模块，分别用于日志记录和单元测试。它们为开发者提供了强大的工具，以确保代码的可靠性和可维护性。以下是对这两个功能的详细解析。

日志功能（log）

日志是开发过程中不可或缺的一部分，它帮助开发者记录程序运行时的状态、错误和调试信息。stdx 模块中的 log 包提供了灵活的日志记录功能，支持多种日志级别和输出格式。

日志级别

log 包支持以下日志级别，开发者可以根据需求选择合适的级别：

日志级别	描述
`TRACE`	用于最详细的调试信息。
`DEBUG`	用于开发阶段的调试信息。
`INFO`	用于记录程序运行状态。
`WARN`	用于记录警告信息。
`ERROR`	用于记录错误信息。
`FATAL`	用于记录致命错误信息。

使用示例

以下是一个使用 log 包的代码示例：

package exampleimport stdx.log.*main () {// 设置日志级别为 DEBUGsetLogLevel(DEBUG)// 记录不同级别的日志trace("This is a TRACE message.")debug("This is a DEBUG message.")info("This is an INFO message.")warn("This is a WARN message.")error("This is an ERROR message.")fatal("This is a FATAL message.")
}

日志输出格式

log 包支持文本格式和 JSON 格式的日志输出。开发者可以通过配置选择适合的输出格式：

单元测试功能（unittest）

单元测试是确保代码质量的重要手段。stdx 模块中的 unittest 包提供了丰富的测试工具，帮助开发者编写和运行单元测试。

测试用例结构

每个测试用例通常包含以下部分：

测试初始化：准备测试环境和数据。
测试执行：调用被测函数或方法。
断言验证：验证测试结果是否符合预期。
测试清理：释放资源或清理环境。

使用示例

以下是一个使用 unittest 包的代码示例：

package exampleimport stdx.unittest.*// 被测函数
function add(a: int, b: int): int {return a + b
}// 测试用例
test "Test add function" {// 测试初始化let result = add(2, 3)// 断言验证assert(result == 5, "Expected 5, but got ${result}")
}

测试报告

unittest 包支持生成详细的测试报告，包括测试通过率、失败原因等信息。以下是一个测试报告的示例表格：

测试用例名称	状态	失败原因
Test add function	PASS	-
Test subtract function	FAIL	Expected 1, but got 2

日志与测试的结合

在实际开发中，日志和测试经常结合使用。例如，在测试用例中记录详细的日志，以便在测试失败时快速定位问题：

test "Test complex function" {info("Starting test for complex function.")let result = complexFunction()assert(result != null, "Result should not be null.")info("Test completed successfully.")
}