跳到主要内容

包

包（模块）系统是代码组织和重用的核心机制。本章将详细介绍 Sii 2 中的 share 和 cite 关键字，以及如何创建和使用模块。

模块系统概述​

Sii 2 使用 share 和 cite 关键字实现模块化：

  • share：用于导出函数和类，使其可以被其他文件使用
  • cite：用于导入其他文件或库中的函数和类

share 关键字​

导出函数​

使用 share 关键字导出函数：

// math.sii
share func add(a: int, b: int): int {
    back a + b;
}

share func subtract(a: int, b: int): int {
    back a - b;
}

share func multiply(a: int, b: int): int {
    back a * b;
}

导出类​

使用 share 关键字导出类：

// user.sii
share class User {
    id: int;
    name: string;
    email: string;
}

share class UserProfile {
    userId: int;
    bio: string;
    avatar: string;
}

share 的限制​

  • 仅支持函数和类：只能导出 func 和 class
  • 不支持变量和常量：不能导出 let 和 const 声明的变量
  • 不支持对象：不能导出 crob 创建的对象
// 可以导出
share func calculate(): int { back 0; }
share class Calculator { }

// 不能导出
// share let value: int = 10;
// share const PI: singlef = 3.14;
// share crob obj = new Calculator();

cite 关键字​

基本语法​

cite 关键字有多种使用方式：

// 1. 默认导入
cite 默认名 from "文件路径";

// 2. 命名导入
cite { 名称1, 名称2 } from "文件路径";

// 3. 混合导入
cite 默认名, { 名称1, 名称2 } from "文件路径";

// 4. 使用别名
cite 源 as 别名 from "文件路径";

本地文件引用​

引用同一项目中的其他文件：

// utils.sii
share func formatString(s: string): string {
    back "[" + s + "]";
}

share class Formatter {
    prefix: string;
}

// main.sii
cite { formatString, Formatter } from "./utils.sii";

let result: string = formatString("Hello");
crob formatter = new Formatter();

相对路径和绝对路径​

// 相对路径
cite { func1 } from "./utils.sii";           // 同级目录
cite { func2 } from "../common/helper.sii";  // 上级目录
cite { func3 } from "./lib/math.sii";        // 子目录

// 绝对路径（如果支持）
// cite { func4 } from "/usr/local/lib/math.sii";

外部库引用​

引用外部库需要使用 lib.库名 格式：

// 引用外部库
cite { sin, cos, tan } from lib.math;

let result: singlef = sin(3.14159 / 2);

库文件命名规则​

  • 库文件格式：库名-版本号.sii（如：math-0.0.1.sii）
  • 版本号：语义化版本格式（X.X.X）
  • 自动选择：系统自动选择最新版本

库管理命令​

# 列出本地库
siic lib list

# 查找最佳匹配的库
siic lib best math
siic lib best math 0.0.1

模块使用示例​

示例 1：数学工具模块​

math.sii

share func add(a: int, b: int): int {
    back a + b;
}

share func subtract(a: int, b: int): int {
    back a - b;
}

share func multiply(a: int, b: int): int {
    back a * b;
}

share func divide(a: int, b: int): int | void {
    if (b == 0) {
        back;
    }
    back a / b;
}

main.sii

cite { add, subtract, multiply, divide } from "./math.sii";

let a: int = 10;
let b: int = 5;

let sum: int = add(a, b);
let diff: int = subtract(a, b);
let product: int = multiply(a, b);
let quotient: int | void = divide(a, b);

sii.io.print("Sum: " + string(sum));
sii.io.print("Difference: " + string(diff));
sii.io.print("Product: " + string(product));
if (typeins(quotient) == "int") {
    sii.io.print("Quotient: " + string(quotient as int));
}

示例 2：用户管理模块​

user.sii

share class User {
    id: int;
    name: string;
    email: string;
}

share func createUser(id: int, name: string, email: string): User {
    let user: User = new User();
    user.id = id;
    user.name = name;
    user.email = email;
    back user;
}

share func getUserInfo(user: User): string {
    back "User #" + string(user.id) + ": " + user.name + " (" + user.email + ")";
}

main.sii

cite { User, createUser, getUserInfo } from "./user.sii";

let user: User = createUser(1, "Alice", "alice@example.com");
let info: string = getUserInfo(user);
sii.io.print(info);

示例 3：多文件模块​

config.sii

share class DatabaseConfig {
    host: string;
    port: int;
    database: string;
}

share func getDefaultConfig(): DatabaseConfig {
    let config: DatabaseConfig = new DatabaseConfig();
    config.host = "localhost";
    config.port = 5432;
    config.database = "mydb";
    back config;
}

db.sii

cite { DatabaseConfig, getDefaultConfig } from "./config.sii";

share func connect(config: DatabaseConfig): bool {
    sii.io.print("Connecting to " + config.host + ":" + string(config.port));
    // 连接逻辑
    back true;
}

main.sii

cite { DatabaseConfig, getDefaultConfig } from "./config.sii";
cite { connect } from "./db.sii";

let config: DatabaseConfig = getDefaultConfig();
let success: bool = connect(config);

命名冲突处理​

使用别名​

当导入的名称与现有名称冲突时，可以使用别名：

// utils1.sii
share func format(s: string): string {
    back "[" + s + "]";
}

// utils2.sii
share func format(s: string): string {
    back "(" + s + ")";
}

// main.sii
cite { format as format1 } from "./utils1.sii";
cite { format as format2 } from "./utils2.sii";

let result1: string = format1("Hello");
let result2: string = format2("World");

模块组织最佳实践​

1. 按功能分组​

将相关的函数和类组织在同一个模块中：

// string-utils.sii - 字符串工具
share func capitalize(s: string): string { }
share func reverse(s: string): string { }

// math-utils.sii - 数学工具
share func factorial(n: int): int { }
share func power(base: int, exp: int): int { }

2. 清晰的模块命名​

模块文件名应该清楚表达其功能：

// 好的命名
user-management.sii
database-connection.sii
file-operations.sii

// 不好的命名
utils.sii
helpers.sii
stuff.sii

3. 避免循环依赖​

避免模块之间的循环依赖：

// 循环依赖
// module1.sii 引用 module2.sii
// module2.sii 引用 module1.sii

// 正确的组织
// common.sii - 公共定义
// module1.sii - 引用 common.sii
// module2.sii - 引用 common.sii

4. 文档注释​

为导出的函数和类添加文档注释：

// calculateArea 计算矩形的面积
// 参数：
//   width: 宽度
//   height: 高度
// 返回：面积
share func calculateArea(width: int, height: int): int {
    back width * height;
}

库开发指南​

库文件结构​

lib/
  math/
    math-0.0.1.sii
    math-0.0.2.sii
  string/
    string-0.0.1.sii

库编写规范​

  1. 所有对外函数必须使用 share
  2. 版本号遵循语义化版本
  3. 提供清晰的文档
  4. 避免依赖特定环境
// math-0.0.1.sii
// 数学函数库 v0.0.1
// 提供基本的数学运算函数

share func add(a: int, b: int): int {
    back a + b;
}

share func subtract(a: int, b: int): int {
    back a - b;
}

模块系统注意事项​

1. 文件路径​

  • 使用字符串字面量指定路径
  • 支持相对路径和绝对路径
  • 路径区分大小写

2. 类型安全​

  • 编译器会检查导入的类型
  • 确保导入的函数签名匹配
  • 确保导入的类结构匹配

3. 运行时支持​

  • 需要运行环境支持模块加载
  • 确保所有依赖的模块都存在
  • 注意模块加载顺序

4. 性能考虑​

  • 避免过深的模块嵌套
  • 合理组织模块大小
  • 避免重复导入

小结​

本章介绍了 Sii 2 的模块系统：

  • share 关键字：导出函数和类
  • cite 关键字：导入模块和库
  • 本地文件引用：引用项目内的文件
  • 外部库引用：引用外部库
  • 命名冲突处理：使用别名解决冲突
  • 最佳实践：如何组织和设计模块

下一章我们将学习异常处理，了解如何优雅地处理错误。