仓颉编程语言 stdx

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

包列表

当前 stdx 提供了如下包：

包名	功能
aspectCJ	aspectCJ 包提供 Cangjie 中面向切面编程（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

1. 从 stdx 项目主页 的发行版处找到对应版本的 stdx 二进制软件包。例如 cangjie-stdx-windows-x64-x.x.x.x.zip 。
2. 将软件包存放到本地某一目录，例如 D 盘的 cangjiestdx 目录。
3. 解压软件包，然后查看 stdx 动态二进制和静态二进制分别在 “D:\cangjiestdx\windows_x86_64_llvm\stdx\dynamic\stdx” 和 “D:\cangjiestdx\windows_x86_64_llvm\stdx\static\stdx” 下。
4. 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\\stdx\\dynamic\\stdx"] # stdx 路径根据实际情况配置

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 Application"
  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 = true
    lto = ""
    [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 的静态二进制，操作步骤如下：

1. 下载 stdx 软件包 cangjie-stdx-linux-x64-x.x.x.x.zip 并解压到 /target。
2. 修改 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"]

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

package test

import stdx.net.http.ServerBuilder

main () {
    // 1. 构建 Server 实例
    let server = ServerBuilder()
                        .addr("127.0.0.1")
                        .port(8080)
                        .build()
    // 2. 注册 HttpRequestHandler
    server.distributor.register("/index", {httpContext =>
        httpContext.responseBuilder.body("Hello 仓颉!")
    })
    // 3. 启动服务
    server.serve()
}

问题反馈

如果您在使用中存在问题，欢迎您在仓颉编程语言社区论坛中通过新建 issue 的方式反馈，官方人员将尽快帮助您解决问题，感谢您的支持与理解！