Sii 完整指南

本指南系统介绍了 Sii 2.x 的各个方面，从基础语法到高级特性，从开发环境到生产部署。

1. 快速入门

Sii 是一门现代静态类型编程工具，设计目标是让开发者用一份代码编译到多个目标平台。Sii 编译器 siic 使用 Rust 编写，具备以下核心特性：

• 多目标编译 — 同一份代码可编译为 JavaScript、TypeScript、WebAssembly (WAT)、LLVM IR 和原生可执行文件
• 强类型系统 — 完整的静态类型检查和类型推断，编译时捕获错误
• Cranelift 原生后端 — 可将 Sii 源码直接编译为机器码，零运行时开销
• 内置开发工具 — 监听模式自动重编译、开发服务器热重载、HTTP 代理
• 丰富的标准库 — 文件 I/O、HTTP 服务器、数据库操作、JSON 处理、系统命令
• 跨平台支持 — Windows、macOS、Linux

你的第一个 Sii 程序

// hello.sii
func main(): void {
    sii.io.print("Hello, Sii!");
}

编译并运行：

# 编译到 JavaScript
siic hello.sii hello.js

# 编译到 TypeScript
siic hello.sii hello.ts --ts

# 编译到原生可执行文件
siic native hello.sii -o hello
./hello

2. 安装与 CLI

从下载页面获取对应平台的 siic 编译器和 sii-runtime-server 运行时。

编译器命令概览

3. 基本概念

标识符与关键字

标识符由字母、数字和下划线组成，不能以数字开头。Sii 是大小写敏感的。

Sii 的保留关键字：

变量声明：let 与 const

// let — 可变变量
let x: int = 42;
x = 100;            // 允许重新赋值

// const — 不可变常量（建议默认使用）
const PI: singlef = 3.14159;
const name: string = "Sii";

// 类型推断 — 当有初始值时类型标注可省略
let autoInt = 42;           // 推断为 int
let autoStr = "hello";      // 推断为 string
const autoBool = true;      // 推断为 bool

作用域

Sii 使用块级作用域（{ }）。内部作用域可以访问外部变量，但反之不行。

let outer: int = 10;

if (outer > 5) {
    let inner: int = 20;
    sii.io.print(outer.toString());   // ok — 访问外部变量
    sii.io.print(inner.toString());   // ok
}

// sii.io.print(inner);  // 错误 — inner 不在作用域内

注释

// 单行注释

/* 多行注释
   可以跨越多行 */

// 文档注释（建议用于 share 函数）
// 计算两数之和
share func add(a: int, b: int): int { back a + b; }

4. 类型系统

Sii 拥有丰富的类型系统，所有类型在编译时确定。

基础类型

复合类型

类型别名

// 使用 type 前缀定义类型别名
let type UserID = int;
let type Point3D = obj;

let id: UserID = 1001;
let point: Point3D = { x: 1, y: 2, z: 3 };

类型检查：typeins()

typeins() 用于在运行时检查变量的实际类型，返回 bool。

let val: unknown = getSomeValue();

if (typeins(val, "int")) {
    // val 是 int 类型
    sii.io.print("整数: " + (val as int).toString());
}
if (typeins(val, "string")) {
    // val 是 string 类型
    sii.io.print("字符串: " + (val as string));
}

类型转换

let n: int = 42;
let s: string = n.toString();     // int → string
let f: singlef = n.toSinglef();   // int → singlef
let d: multif = n.toMultif();     // int → multif

let pi: singlef = 3.14;
let piInt: int = pi.toInt();      // singlef → int (截断)

5. 函数

函数声明

// 基本函数 — func 关键字，参数需要类型标注
func add(a: int, b: int): int {
    back a + b;
}

// 无返回值
func log(msg: string): void {
    sii.io.print(msg);
    // back 可省略
}

// 无参数
func getVersion(): string {
    back "2.0.0";
}

返回值：back 关键字

Sii 使用 back 关键字返回函数结果（等价于其他编程环境的 return）。

func max(a: int, b: int): int {
    if (a > b) {
        back a;
    }
    back b;
}

func greet(name: string): string {
    back "Hello, " + name + "!";
}

递归函数

func factorial(n: int): int {
    if (n <= 1) { back 1; }
    back n * factorial(n - 1);
}

func fibonacci(n: int): int {
    if (n <= 1) { back n; }
    back fibonacci(n - 1) + fibonacci(n - 2);
}

6. 控制流

if / else if / else

let score: int = 85;

if (score >= 90) {
    sii.io.print("优秀");
} else if (score >= 60) {
    sii.io.print("及格");
} else {
    sii.io.print("不及格");
}

注意：条件表达式不需要括号，但这里为了清晰保留。两种写法均可。

forloop — C 风格 for 循环

// 标准 forloop
forloop (let i = 0; i < 10; i = i + 1) {
    sii.io.print(i.toString());
}

// 遍历数组
let items: arr<string> = ["a", "b", "c"];
forloop (let i = 0; i < items.length().toInt(); i = i + 1) {
    sii.io.print(items[i]);
}

while 循环

let count: int = 3;
while (count > 0) {
    sii.io.print(count.toString());
    count = count.toDn(1);  // 自减
}

break 与 continue

forloop (let i = 0; i < 100; i = i + 1) {
    if (i == 5) { continue; }   // 跳过本次迭代
    if (i == 10) { break; }      // 终止循环
    sii.io.print(i.toString());
}

自增/自减方法

7. 类与对象

class — 结构体定义

class 在 Sii 中用于定义数据结构（类似 C 的 struct），只包含字段，不含方法。

// 声明一个类（数据结构）
class Point {
    x: int;
    y: int;
}

class User {
    id: int;
    name: string;
    email: string;
    active: bool;
}

// 创建实例
let origin = new Point();
origin.x = 0;
origin.y = 0;

let user = new User();
user.name = "Alice";

crob — 封装对象（字段 + 方法）

crob 是 Sii 的核心对象创建机制。它基于一个 class 创建封装对象，可以添加字段值和方法。

class Person {
    name: string;
    age: int;
}

// 简单 crob
crob alice(class: Person, right: true) {
    name = "Alice";
    age = 28;
}

// 封装 crob — 包含方法
crob bob(class: Person, right: true) {
    name = "Bob";
    age = 32;

    func greet(): string {
        back "Hi, I'm " + name + ", age " + age.toString();
    }

    func haveBirthday(): void {
        age = age.getUp(1);
    }
}

// 调用方法
let greeting = bob.greet();
bob.haveBirthday();

remake — 重构对象

// 基于已有的 crob 创建新对象，修改部分字段
remake alice {
    age = 29;  // 年龄更新
    // name 保持不变
}

this 关键字

this 在 crob 方法中引用当前对象实例：

crob counter(class: Box, right: true) {
    value = 0;

    func increment(): int {
        value = value.getUp(1);
        back this.value;  // 等价于直接 back value
    }
}

8. 数组与集合

数组字面量

let nums: arr<int> = [1, 2, 3, 4, 5];
let names: arr<string> = ["Alice", "Bob", "Charlie"];
let empty: arr<int> = [];

索引访问

let first = nums[0];      // 读取
nums[2] = 10;              // 修改（可变数组）
let last = nums[nums.length().toInt() - 1];

push — 追加元素

push 6 => nums[nums.length().toInt()];
push "Diana" => names[names.length().toInt()];

rmv — 删除元素

rmv nums[2];    // 删除索引 2 的元素
rmv names[0];   // 删除第一个元素

数组遍历

let items: arr<string> = ["a", "b", "c", "d"];

// 方式 1：forloop
forloop (let i = 0; i < items.length().toInt(); i = i + 1) {
    sii.io.print("[" + i.toString() + "] " + items[i]);
}

// 方式 2：while
let j = 0;
while (j < items.length().toInt()) {
    sii.io.print(items[j]);
    j = j.getUp(1);
}

数组方法

let nums: arr<int> = [1, 2, 3, 4, 5];
let slice = nums.cutIt(1, 3);  // [2, 3]
nums.splice(2, 1);              // 删除索引 2 的元素 → [1, 2, 4, 5]

9. 模块系统

share — 导出

使用 share 关键字导出函数和类（只有函数和类可以被导出）：

// math.sii
share func add(a: int, b: int): int { back a + b; }
share func sub(a: int, b: int): int { back a - b; }
share class Point { x: int; y: int; }

// 内部辅助函数（不导出）
func internalHelper(): void { /* ... */ }

cite — 导入

使用 cite 关键字从其他 Sii 文件导入：

// 默认导入（导入文件中所有 share 的内容）
cite math from "./math.sii";

// 命名导入 — 只导入特定符号
cite { add, sub } from "./math.sii";

// 别名导入
cite add as myAdd from "./math.sii";
cite { add, sub as subtract } from "./math.sii";

// 导入运行时模块
cite sii.io as io;
cite sii.db as db;

外部库引用（lib.库名）

// 引用已安装的外部库
cite math from "lib.math";        // 引用 math 库的默认导出
cite { sin, cos } from "lib.math"; // 命名引用

外部库通过 sii install <库名> 安装，存储在用户级库目录中。

10. 异常处理

Sii 没有传统的 try-catch 异常机制。错误处理通过返回值检查和错误码来完成，这是一种显式的错误处理风格。

错误码体系

检查错误

// 文件操作返回值检查
let content = sii.readText("config.json");
if (typeins(content, "string")) {
    // 读取成功
    sii.io.print(content as string);
} else {
    // 读取失败
    sii.io.print("无法读取配置文件");
}

// 使用 typeins 验证返回值
let result = performOperation();
if (typeins(result, "int")) {
    let code = result as int;
    if (code == 0) {
        sii.io.print("操作成功");
    } else {
        sii.io.print("错误码: " + code.toString());
    }
}

11. 标准库

Sii 提供丰富的内置标准库，通过 sii.* 命名空间访问。

11.1 控制台 I/O

// 基本输出
sii.io.print("Hello, World!");
sii.io.print("The answer is", 42);

// 读取输入
let name = sii.io.readLine();
sii.io.print("你好, " + name + "!");

11.2 文件系统

// 读取文件
let config = sii.readText("config.json");
let data = sii.jsonParse(config);

// 写入文件
let json = sii.jsonStringify({ version: "2.0", debug: true });
sii.writeText("output.json", json);

// 路径操作
let logPath = sii.pathJoin(sii.cwd(), "logs", "app.log");
if (!sii.exists(logPath)) {
    sii.mkdirs(sii.pathJoin(sii.cwd(), "logs"));
    sii.writeText(logPath, "");
}

11.3 JSON 处理

11.4 网络编程

HTTP 客户端

// GET 请求
let resp = sii.get("https://api.example.com/data");
sii.io.print(resp);

// POST 请求
let result = sii.post("https://api.example.com/submit", jsonData);

HTTP 服务器

func main(): void {
    sii.listen(3000);

    // 路由注册
    sii.get("/", func(): string {
        back "Welcome to Sii Server!";
    });

    sii.get("/api/users", func(): string {
        let users = sii.jsonStringify([
            { id: 1, name: "Alice" },
            { id: 2, name: "Bob" }
        ]);
        back users;
    });

    sii.post("/api/submit", func(): string {
        // 处理 POST 数据...
        back sii.jsonStringify({ ok: true });
    });

    sii.io.print("服务器已启动: http://127.0.0.1:3000");
}

11.5 数据库操作

Sii 提供链式查询 API，支持 MySQL、PostgreSQL 和 SQLite。

// 连接数据库
sii.db.connect("mysql", "mysql://user:pass@localhost/mydb");
// 或
sii.db.connect("postgresql", "postgresql://user:pass@localhost/mydb");
// 或
sii.db.connect("sqlite", "sqlite:data.db");

// 链式查询
let rows = sii.db.table("users")
    .where("age", ">=", 18)
    .where("status", "=", "active")
    .orderBy("created_at", "DESC")
    .limit(10)
    .find();

// 遍历结果
forloop (let i = 0; i < rows.length().toInt(); i = i + 1) {
    let user = rows[i];
    sii.io.print(user.name + " - " + user.email);
}

11.6 系统命令与工具

// 执行命令
let code = sii.exec("echo hello");
let gitLog = sii.execOut("git log --oneline -5");

// 环境变量
let home = sii.env("HOME");
let path = sii.env("PATH");

// 日志
sii.log("应用启动");
sii.warn("配置项缺失，使用默认值");
sii.error("数据库连接失败");

12. 编译与构建

编译目标

监听模式

# 文件变化自动重编译
siic watch hello.sii hello.js

# 可同时指定多个编译目标
siic watch hello.sii hello.js
# 在另一个终端
siic watch hello.sii hello.ts --ts

开发服务器

# 启动开发服务器（默认端口 4173）
siic serve hello.sii

# 指定端口
siic serve hello.sii --port=8080

# 带反向代理（将 API 请求代理到后端）
siic serve hello.sii --proxy=http://localhost:3001

原生编译详解

siic native 使用 Cranelift 代码生成器将 Sii 源码编译为机器码，链接 libsii_rt_core.a 生成独立可执行文件。

# 编译为原生可执行文件
siic native hello.sii -o hello
./hello

# 交叉编译到其他平台
siic native hello.sii -o hello.exe -t=x64-windows
siic native hello.sii -o hello_arm -t=arm64-linux

LLVM 工具链（可选）

13. VS Code 扩展 (Sii Assistant)

Sii Assistant 是官方 VS Code 扩展，为 .sii 文件提供语法高亮、智能补全、悬停文档，以及一键编译和运行能力。

安装

从下载页面获取最新 .vsix 文件，然后：

# 命令行安装
code --install-extension sii-lang-vscode-0.0.2.vsix

# 或在 VS Code 界面中
# 扩展面板 (Ctrl+Shift+X) → ... 菜单 → "从 VSIX 安装..."

功能一览

编译命令

打开 .sii 文件后，通过命令面板 (Ctrl+Shift+P) 或右键菜单使用：

扩展设置

在 VS Code 设置中搜索 "Sii" 可配置以下选项：

14. 部署与运行

运行时服务器

当编译目标为 JavaScript、TypeScript 或 WebAssembly 时，需要 sii-runtime-server 提供 I/O、数据库等后端能力。

# 启动运行时服务器
./sii-runtime-server --port=4174 &

# 运行编译后的 JS 程序
node app.js

# 或使用 siic serve 一键启动
siic serve app.sii --port=4173 --proxy=http://localhost:4174

Docker 部署

# Dockerfile
FROM node:20-alpine
COPY sii-runtime-server /usr/local/bin/
COPY app.js /app/
WORKDIR /app
CMD ["sh", "-c", "sii-runtime-server & sleep 1 && node app.js"]

# 构建和运行
docker build -t sii-app .
docker run -p 3000:3000 sii-app

systemd 服务（Linux）

# /etc/systemd/system/sii-app.service
[Unit]
Description=Sii Application
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/sii-runtime-server --port=4174
Restart=always
User=app

[Install]
WantedBy=multi-user.target

原生二进制部署

使用 siic native 编译出的可执行文件完全独立，无需运行时服务器。直接复制到目标机器即可运行：

# 编译
siic native app.sii -o myapp

# 部署
scp myapp user@server:/opt/myapp/
ssh user@server /opt/myapp/myapp

15. 附录

关键字完整列表

运算符优先级（从高到低）

标准库速查表

常见问题 (FAQ)

Q: Sii 和 TypeScript 有什么区别？

Sii 是一套独立的编程工具链，拥有自己的编译器、类型系统和运行时。它可以编译到 TypeScript，但本身不是 TypeScript 的超集。Sii 的类型系统更加严格，语法更简洁，并且支持原生编译。

Q: 什么时候应该用原生编译？

当你需要最高性能、最小启动时间，或者希望分发独立的二进制文件（无需 Node.js 或运行时服务器）时，使用 siic native。

Q: 编译后的 JS 代码必须依赖运行时服务器吗？

如果 Sii 代码中使用了 I/O、数据库、HTTP 服务器等需要系统级支持的功能，则需要运行时服务器。纯计算逻辑（不涉及这些）编译后的 JS 代码可以独立运行。

Q: 如何安装第三方库？

使用 sii install <库名> 命令安装，然后在代码中通过 cite ... from "lib.库名" 引用。

Q: Sii 1.x 的代码能在 Sii 2.x 上运行吗？

大部分语法是兼容的。Sii 2.x 是全新编译器实现，某些细节行为可能有差异。建议参考本指南适配。