仓颉之包与异常处理的智慧战场

1 概述

1.1 背景介绍

仓颉编程语言作为一款面向全场景应用开发的现代编程语言，通过现代语言特性的集成、全方位的编译优化和运行时实现、以及开箱即用的 IDE工具链支持，为开发者打造友好开发体验和卓越程序性能。

案例结合代码体验，帮助大家更直观的了解仓颉语言中包的定义和导入和异常处理知识。

1.2 适用对象

• 个人开发者
• 高校学生

1.3 案例时间

本案例总时长预计40分钟。

1.4 案例流程

说明：

① 进入华为开发者空间，登录云主机；
② 使用CodeArts IDE for Cangjie编程和运行仓颉代码。

1.5 资源总览

资源名称	规格	单价（元）	时长（分钟）
开发者空间 - 云主机	鲲鹏通用计算增强型 kc2 | 4vCPUs | 8G | Ubuntu	免费	40

仓颉之包与异常处理的智慧战场 👈👈👈体验完整版案例，点击这里。

2 环境准备

2.1 开发者空间配置

面向广大开发者群体，华为开发者空间提供一个随时访问的“开发桌面云主机”、丰富的“预配置工具集合”和灵活使用的“场景化资源池”，开发者开箱即用，快速体验华为根技术和资源。

领取云主机后可以直接进入华为开发者空间工作台界面，点击打开云主机 > 进入桌面连接云主机。没有领取在开发者空间根据指引领取配置云主机即可，云主机配置参考1.5资源总览。

点击桌面CodeArts IDE for Cangjie，打开编辑器，点击新建工程，名称demo，其他保持默认配置，点击创建。

产物类型说明：

• executable，可执行文件；
• static，静态库，是一组预先编译好的目标文件的集合；
• dynamic，动态库，是一种在程序运行时才被加载到内存中的库文件，多个程序共享一个动态库副本，而不是像静态库那样每个程序都包含一份完整的副本。

创建完成后，打开src/main.cj，点击编辑器右上角运行按钮直接运行，终端窗口可以看到打印内容。

后续文档中的代码验证均可以替换main.cj中的代码（package demo包路径保留）后执行，demo是项目名称，与创建项目时设置的保持一致。

至此，云主机环境配置完毕。

3 包

3.1 包及包的声明

在仓颉编程语言中，项目通过包和模块实现代码的模块化管理和规模化协作。其中，包是编译的最小单元，每个包可以单独输出 AST 文件、静态库文件、动态库文件等产物，一个包可以包含多个源文件；模块是若干包的集合，是第三方开发者发布的最小单元。一个模块的程序入口只能在其根目录下，它的顶层最多只能有一个作为程序入口的main。

使用场景示例：开发一个网络应用时，可将核心逻辑、数据库交互、HTTP 接口分别封装为 core、db、api 三个包，组合成一个模块。第三方开发者通过导入该模块的库文件，快速调用相关功能。

3.1.1 包的声明

仓颉中包的声明格式以关键字package开头，后接root包至当前包，用 . 分隔包名。语法格式：

package pkg1[．pkg2[．pkg3…]]

举例：

package pkg1      // root 包 pkg1
package pkg1.sub1 // root 包 pkg1 的子包 sub1

（* 注意：包声明必须在源文件的非空非注释的首行，且同一个包中的不同源文件的包声明必须保持一致）

包名需反映文件在项目 src 目录下的相对路径，路径中的 “/” 替换为 “.” ，"src"是源码根目录，默认不参与包名构成。另外，包声明不能引起命名冲突：子包不能和当前包的顶层声明同名，例如：

// 1. 源文件a.cj
package demo.a
public class B { // 错误，'B'与子包'a.B'冲突
    public static func f() {}
}
// 2. 源文件b.cj
package demo.a.B
public func f() {}

在项目根目录"src"下创建两个目录a/B，并在a目录下创建a.cj，复制粘贴以上源文件a.cj代码；在a/B目录下创建b.cj，复制粘贴以上源文件b.cj代码。可以看到a.cj中因顶层声明` B `与可能的子包` demo.a `冲突而报错。

3.1.2 顶层声明的可见性

通过包进行源文件划分隔离后，那么类型、变量、函数等顶层声明的可见性也需要更加细粒度的控制。

1. 访问修饰符

仓颉中提供了4 种访问修饰符：private、internal、protected、public，在修饰顶层元素时不同访问修饰符的语义如下：

• private 表示仅当前文件内可见。不同的文件无法访问这类成员。
• internal 表示仅当前包及子包（包括子包的子包）内可见。同一个包内可以不导入就访问这类成员，当前包的子包（包括子包的子包）内可以通过导入来访问这类成员。
• protected 表示仅当前模块内可见。同一个包的文件可以不导入就访问这类成员，不同包但是在同一个模块内的其它包可以通过导入访问这些成员，不同模块的包无法访问这些成员。
• public 表示模块内外均可见。同一个包的文件可以不导入就访问这类成员，其它包可以通过导入访问这些成员。

访问修饰符	源文件	包及子包	模块	所有包
private	Y	N	N	N
internal	Y	Y	N	N
protected	Y	Y	Y	N
public	Y	Y	Y	Y

（* Y——可以访问；N——无法访问）

不同顶层声明支持的访问修饰符和默认修饰符规定如下：

• pacakge 支持使用 internal、protected、public，默认修饰符为 public。
• import 支持使用全部访问修饰符，默认修饰符为 private。
• 其他顶层声明支持使用全部访问修饰符，默认修饰符为 internal。

package test

private func f1() { 1 }   // f1 仅在当前文件内可见
func f2() { 2 }           // f2 仅当前包及子包内可见
protected func f3() { 3 } // f3 仅当前模块内可见
public func f4() { 4 }    // f4 当前模块内外均可见 

（* 在仓颉中，用一对大括号“{}”包围一段仓颉代码，即构造了一个新的作用域，特别的，在一个仓颉源文件中，不被任何大括号“{}”包围的代码，它们所属的作用域被称为“顶层作用域”）

2. 访问级别排序

仓颉的访问级别排序为 public > protected > internal > private。声明中使用的类型访问级别不得低于其自身。常见错误编码示例：

class C {}		// 默认修饰符，internal
// 1. 函数参数/返回值类型不兼容
public func f1(a1: C) // 错误，public声明f1不能使用internal类型C
{
    return 0
}
public func f2(a1: Int8): C // 错误，public声明f2不能使用internal类型C
{
    return C()
}
// 2. 类型不兼容
public let v1: C = C() // 错误，public声明v1不能使用internal类型C
public let v2 = C() // 错误，public声明v2不能使用internal类型C
// 3. 继承/实现冲突
open class C1 {}	// 默认修饰符，internal
interface I {}		// 默认修饰符，internal
public class C2 <: C1 {} // 错误，public声明类C2不能继承internal类型C1
public enum E <: I { A } // 错误，public声明枚举E不能实现internal类型I

复制以上代码，替换main.cj文件中的代码（保留package），可以看到编辑器检查到代码存在问题：

例外情况，public 声明的内部逻辑：允许在函数体或初始化表达式中使用本包内的非 public 类型。

class C1 {}
public func f2(a1: Int8)
{
  var v1 = C1()	// Ok.
  return 0
}
public class C2
{
  var v2 = C1()	// Ok.
}

复制以上代码，替换main.cj文件中的代码（保留package），可以看到在f2函数体中和C2类属性定义中使用包内非public修饰的C1类并未报错：

（* 注意：内置类型诸如 Rune、Int64 等都默认是 public 的）

3.2 包的导入

3.2.1 Import导入

在仓颉编程语言中，使用import语句导入其它包中的声明或定义，语法结构：

• 使用 import fullPackageName.itemName 导入特定声明。
• 一次导入多个包可用 import fullPackageName.{itemName1, itemName2}，如果导入的多个 itemName 同属于一个 fullPackageName，可以使用 import fullPackageName.{itemName[, itemName]*} 语法。
• 可以使用通配符导入包中所有可见声明和定义，如：import packageName.*。

（* fullPackageName 为完整路径包名，itemName 为声明的名字）

package a
import package1.foo					// 导入一个特定的顶层声明
import {package1.foo, package2.bar}	// 一次导入多个声明，不同包下
import package1.{foo, bar, fuzz}		// 一次导入多个声明，同一包下
import package1.*						// 导入包所有可见声明和定义

需要注意：

• 导入的成员的作用域级别低于当前包声明的成员。
• 当已导出的包的模块名或者包名被篡改，使其与导出时指定的模块名或包名不一致，在导入时会报错。
• 只允许导入当前文件可见的顶层声明或定义，导入不可见的声明或定义将会在导入处报错。
• 禁止通过 import 导入当前源文件所在包的声明或定义。
• 禁止包间的循环依赖导入，如果包之间存在循环依赖，编译器会报错。

另外，在仓颉编程语言中，导入的声明或定义如果和当前包中的顶层声明或定义重名且不构成函数重载，则导入的声明和定义会被遮盖；导入的声明或定义如果和当前包中的顶层声明或定义重名且构成函数重载，函数调用时将会根据函数重载的规则进行函数决议。

在项目根目录src下创建目录a，并在a目录下创建a.cj，复制粘贴以上源文件a.cj代码；复制粘贴以上源文件main.cj代码到main.cj 。

// 1. 源文件a.cj
package demo.a

public struct R {   // R1
    let name = "R1"
}
public func f(a: Int32) {    // f1
    println("f1")
}
public func f(a: Bool) {    // f2，与 f1 是重载函数
    println("f2")
}

// 2. 源文件main.cj
package demo
import demo.a.*

func f(a: Int32) {      // f3，会遮盖a.cj中f1，并与f2构成函数重载
    println("f3")
}
struct R {             // R2，会覆盖a.cj中R1
    var name = "R2"
}
main() {
    var r = R()     // OK, R2 覆盖 R1.
    println("结构体：${r.name}")
    f(1)    // OK, 调用当前包中的f3
    f(true) // OK, 调用导入包中的f2
}

然后运行main.cj（告警日志会提示某些定义未被使用，忽略即可），终端输出：

（* 诸如 String、Range 等类型能直接使用，并不是因为这些类型是内置类型，而是因为编译器会自动为源码隐式的导入 core 包中所有的 public 修饰的声明）

3.2.2 重命名导入

在导入不同包的同名顶层声明时，支持使用 import packageName.name as newName 的方式进行重命名来避免冲突。当然，没有同名冲突也可以使用重命名导入声明。重命名导入规则如下：

• 使用 import as 对导入的声明进行重命名后，当前包只能使用重命名后的新名字，原名无法使用。
• 如果重命名后的名字与当前包顶层作用域的其它名字存在冲突，且这些名字对应的声明均为函数类型，则参与函数重载，否则报重定义的错误。
• 支持 import pkg as newPkgName 的形式对包名进行重命名，以解决不同模块中同名包的命名冲突问题。

（* 注意：如果没有对导入的存在冲突的名字进行重命名，在import语句处不报错；在使用处，会因为无法导入唯一的名字而报错）

在项目根目录src下创建目录a，并在a目录下创建a.cj，复制粘贴以上源文件a.cj代码；同理创建b目录并复制粘贴源文件b.cj代码；复制粘贴以上源文件main.cj代码到main.cj。

// 1. 源文件a.cj
package demo.a
public func f1() {
	println("包a下的f1函数……")
}

// 2. 源文件b.cj
package demo.b
public func f1() {
	println("包b下的f1函数……")
}

// 3. 源文件main.cj
package demo
import demo.a as A	// 对包名进行重命名
import demo.b as B
import demo.a.f1 as f  // 和当前包顶层作用域f函数构成函数重载

func f(a: Int32) {
	println("当前包下的f函数……")
}

main() {
    A.f1()
    B.f1()
    f() 		// 函数重载
    f(10)		// 函数重载
}

然后运行main.cj（告警日志会提示某些定义未被使用，忽略即可），终端输出：

3.2.3 重导出

前面介绍到，import默认的访问修饰符是private，而当import被 public、protected 或者 internal 修饰的 import 可以把导入的成员重导出，其它包可以根据可见性直接导入并使用本包中用重导出的内容。

具体被不用访问修饰符修饰时的可访问范围参考3.1.2 顶层声明的可见性中访问修饰符介绍。

（* 注意：包不可以被重导出，如果被 import 导入的是包，那么该 import 不允许被 public、protected 或者 internal 修饰）

在项目根目录src下创建目录a，并在a目录下创建a.cj，复制粘贴以上源文件a.cj代码；同理创建b目录并复制粘贴源文件b.cj代码；复制粘贴以上源文件main.cj代码到main.cj。

// 1. 源文件a.cj
package demo.a
// 重导出
public import demo.b.f

// 2. 源文件b.cj
public package demo.b
public func f() {
	println("包b下的f函数……")
}

// 3. 源文件 main.cj
package demo
import demo.a.f as f

main() {
    f()
}

然后运行main.cj，终端输出：

3.3 程序入口

仓颉程序入口为 main，源文件根目录下的包的顶层最多只能有一个 main。

如果模块采用生成可执行文件的编译方式，编译器只在源文件根目录下的顶层查找 main。如果没有找到，编译器将会报错；如果找到 main，编译器会进一步对其参数和返回值类型进行检查。需要注意的是，main 不可被访问修饰符修饰，当一个包被导入时，包中定义的 main 不会被导入。

main 可以没有参数或参数类型为 Array<String>，返回值类型为 Unit 或整数类型。

没有参数，返回值类型为整数类型：

main(): Int64 {
    return 0
}
参数类型为 Array<String>，返回值类型为Unit：
main(args: Array<String>): Unit {
    for (arg in args) {
        println(arg)
    }
}

当main参数类型为Array<String>时，可以在运行时传参。将上面代码复制到main.cj后，打开终端，执行以下命令编译运行main.cj。

cjc ./src/main.cj
./main Hello,仓颉 

4 异常

4.1 异常定义

异常不属于程序的正常功能，一旦发生异常，要求程序必须立即处理，即将程序的控制权从正常功能的执行处转移至处理异常的部分。仓颉编程语言提供异常处理机制用于处理程序运行时可能出现的各种异常情况。

在仓颉中，异常类有 Error 和 Exception：

• Error 类描述仓颉语言运行时，系统内部错误和资源耗尽错误，如果出现内部错误，只能通知给用户，尽量安全终止程序。
• Exception 类描述的是程序运行时的逻辑错误或者 IO 错误导致的异常，这类异常需要在程序中捕获处理。

如果要自定义异常，需要集成内置的Exception或其子类，不能用Error及其子类。

Error 的主要函数及其说明：

函数种类	函数	说明
成员属性	open prop message: String	发生错误的详细信息。
成员函数	open func toString(): String	返回错误类型名以及错误的详细信息。
成员函数	func printStackTrace(): Unit	打印堆栈信息至标准错误流。

Exception 的主要函数及其说明：

函数种类	函数	说明
构造函数	init()	默认构造函数。
构造函数	init(message: String)	可以设置异常消息的构造函数。
成员属性	open prop message: String	发生异常的详细信息。
成员函数	open func toString(): String	返回异常类型名以及异常的详细信息。
成员函数	func getClassName(): String	返回用户定义的类名。
成员函数	func printStackTrace(): Unit	打印堆栈信息至标准错误流。

4.2 异常处理

上面介绍了异常定义，接下来学习如何抛出和处理异常。

4.2.1 throw关键字

仓颉语言提供 throw 关键字，用于抛出异常。用 throw 来抛出异常时，throw 之后的表达式必须是 Exception 的子类型。

throw 关键字抛出的异常需要被捕获处理。若异常没有被捕获，则由系统调用默认的异常处理函数。

异常处理由 try 表达式完成，可分为：

• 不涉及资源自动管理的普通 try 表达式；
• 会进行资源自动管理 try-with-resources 表达式。

4.2.2 普通try表达式

普通 try 表达式包括三个部分：try 块，catch 块和 finally 块。每部分介绍：

• try块：try以关键字 try 开始，后面紧跟一个由表达式与声明组成的块。try 后面的块内可以抛出异常，并被紧随的 catch 块所捕获并处理（如果不存在 catch 块或未被捕获，则在执行完 finally 块后，该异常继续被抛出，所以，当没有catch块时必须有finally块）。
• catch块：一个普通 try 表达式可以包含零个或多个 catch 块。每个 catch 块以关键字 catch 开头，后跟一条 catchPattern 和一个块，catchPattern 通过模式匹配的方式匹配待捕获的异常。
• finally 块：以关键字 finally 开始，后面紧跟一个块。finally 块中主要实现一些“善后”的工作，如释放资源等，要尽量避免在 finally 块中再抛异常，且无法 try 块中是否发生异常，finally块内容都会被执行。

（* 注意：catch块中catchPattern的类型模型可以配置仅指定一个异常类，也可以通过 | 符号指定多个案例）

main() {
    try {
        throw NegativeArraySizeException("存在大小为负的数组异常!")
    } catch (e: NegativeArraySizeException) {
        print("NegativeArraySizeException异常触发! ")
        println("异常信息: ${e}")
    } catch (e: IllegalArgumentException | OverflowException) {
        print("IllegalArgumentException 或 OverflowException 异常触发! ")
        println("异常信息: ${e}")
    } finally {
        println("finally块被执行。")
    }
}

复制以上代码，替换main.cj文件中的代码（保留package），运行将输出：

4.2.3 try-with-resource表达式

try-with-resources 表达式主要是为了自动释放非内存资源。不同于普通 try 表达式，try-with-resources 表达式中的 catch 块和 finally 块均是可选的，并且 try 关键字其后的块之间可以插入一个或者多个 ResourceSpecification 用来申请一系列的资源。

（* ResourceSpecification是实例化一系列的对象，多个实例化之间使用“,”分隔）

// 定义一个 Worker 类，继承自 Resource（资源管理基类）
class Worker <: Resource {
    var hasTools: Bool = false    // 表示工人是否持有工具
    let name: String              // 工人姓名
    // 构造函数，初始化工人姓名
    public init(name: String) {
        this.name = name
    }
    // 获取工具函数：从仓库领取工具并更新状态
    public func getTools() {
        println("${name} 从仓库拿起工具。")
        hasTools = true
    }
    // 工作函数：根据是否持有工具执行不同操作
    public func work() {
        if (hasTools) {
            println("${name} 使用工具工作。")
        } else {
            println("${name} 没有工具，没做工作。")
        }
    }
    // 检查资源是否已关闭（工具是否归还）
    public func isClosed(): Bool {
        if (hasTools) {
            println("${name} 还没有归还工具。")
            false
        } else {
            println("${name} 没有工具。")
            true
        }
    }
    // 关闭资源方法：归还工具到仓库
    public func close(): Unit {
        println("${name} 把工具归还工具到仓库。")
        hasTools = false
    }
}
// 主函数演示三种场景
main() {
    // 场景1：正常使用工具（自动资源管理）
    try (r = Worker("Tom")) {
        r.getTools()
        r.work()
    }// 此处自动调用 close()，Tom 归还工具
    // 场景2：未获取工具直接工作
    try (r = Worker("Bob")) {
        r.work()
    }// 自动检查发现无工具，无需归还
    // 场景3：操作过程中发生异常
    try (r = Worker("Jack")) {
        r.getTools()
        // 模拟突发异常
        throw Exception("Jack 因有紧急情况离开了。") 
    }// 即使发生异常，仍会自动调用 close() 确保工具归还
}

复制以上代码，替换main.cj文件中的代码（保留package），运行将输出：

至此，仓颉语言中包和异常处理的知识内容介绍告一段落。

如果想了解更多仓颉编程语言知识可以访问： https://cangjie-lang.cn/

如果想要了解仓颉标准库提供的模块可以访问：https://cangjie-lang.cn/docs?url=%2F0.53.18%2Flibs%2Flibs_overview.html