跳到主要内容

标准库

Sii 语言提供了丰富的标准库函数,通过 sii. 前缀调用,包括文件操作、系统调用、HTTP服务等功能。

文件操作

文件读写

sii.readText()

读取文件内容并返回字符串。

语法:

sii.readText(文件路径: string): string

参数:

  • 文件路径:要读取的文件路径(字符串类型)

返回值:

  • 文件内容(字符串类型)

示例:

let content: string = sii.readText("./config.json");

sii.writeText()

将内容写入文件。

语法:

sii.writeText(文件路径: string, 内容: string): void

参数:

  • 文件路径:要写入的文件路径(字符串类型)
  • 内容:要写入的内容(字符串类型)

返回值:

  • 无返回值(void)

示例:

sii.writeText("./log.txt", "应用启动时间:" + string(sii.now()));

示例:

// 读取配置文件
let config: string = sii.readText("./config.json");
sii.log("配置内容:" + config);

// 写入日志文件
sii.writeText("./log.txt", "应用启动时间:" + string(sii.now()));

文件系统操作

sii.exists()

检查文件或目录是否存在。

语法:

sii.exists(路径: string): obj

参数:

  • 路径:要检查的文件或目录路径(字符串类型)

返回值:

  • 存在状态(对象类型)

sii.mkdirs()

创建目录(包括父目录)。

语法:

sii.mkdirs(目录路径: string): void

参数:

  • 目录路径:要创建的目录路径(字符串类型)

返回值:

  • 无返回值(void)

sii.pathJoin()

拼接路径。

语法:

sii.pathJoin(路径1: string, 路径2: string): string

参数:

  • 路径1:第一个路径(字符串类型)
  • 路径2:第二个路径(字符串类型)

返回值:

  • 拼接后的完整路径(字符串类型)

sii.cwd()

获取当前工作目录。

语法:

sii.cwd(): string

参数:

  • 无参数

返回值:

  • 当前工作目录路径(字符串类型)

示例:

// 检查并创建目录
if (sii.exists("./data")) {
sii.log("数据目录已存在");
} else {
sii.mkdirs("./data");
sii.log("数据目录已创建");
}

// 构建文件路径
let logFile: string = sii.pathJoin(sii.cwd(), "logs", "app.log");
sii.writeText(logFile, "应用日志");

系统操作

环境变量

sii.env()

获取环境变量值。

语法:

sii.env(变量名: string): string

参数:

  • 变量名:环境变量名称(字符串类型)

返回值:

  • 环境变量值(字符串类型)

示例:

let homeDir: string = sii.env("HOME");
let nodeEnv: string = sii.env("NODE_ENV");

时间戳

sii.now()

警告

注意:此功能当前已放弃支持,最高适配版本为 v1.1.0。

获取当前时间戳。

语法:

sii.now(): int

参数:

  • 无参数

返回值:

  • 当前时间戳(整数类型)

示例:

let timestamp: int = sii.now();
sii.log("当前时间戳:" + string(timestamp));

日期时间处理

提示

版本要求:以下功能从 v1.2.1 开始支持

sii.Date

格式化当前日期时间。

语法:

sii.Date(): string
sii.Date(格式字符串: string): string

参数:

  • 无参数:返回 ISO 格式的日期时间字符串
  • 格式字符串:指定日期时间格式

返回值:

  • 格式化后的日期时间字符串

格式字符串支持:

  • YYYY:四位数年份
  • MM:两位数月份(01-12)
  • DD:两位数日期(01-31)
  • HH:两位数小时(00-23)
  • mm:两位数分钟(00-59)
  • ss:两位数秒数(00-59)
  • Y:年份(不补零)
  • M:月份(不补零)
  • D:日期(不补零)
  • H:小时(不补零)
  • m:分钟(不补零)
  • s:秒数(不补零)

示例:

// 获取 ISO 格式日期时间
let isoTime: string = sii.Date();
print("ISO格式:" + isoTime);

// 获取时间戳
let timestamp: int = sii.Date("now");
print("时间戳:" + string(timestamp));

// 自定义格式
let customFormat: string = sii.Date("YYYY-MM-DD HH:mm:ss");
print("自定义格式:" + customFormat);

// 简单格式
let simpleFormat: string = sii.Date("Y-M-D H:m:s");
print("简单格式:" + simpleFormat);

完整示例:

// 记录当前时间
let currentTime: string = sii.Date("YYYY-MM-DD HH:mm:ss");
print("当前时间:" + currentTime);

// 获取时间戳用于计算
let now: int = sii.Date("now");
print("当前时间戳:" + string(now));

// 格式化日志时间
let logTime: string = sii.Date("MM-DD HH:mm");
print("日志时间:" + logTime);

进程执行

sii.exec()

执行系统命令。

语法:

sii.exec(命令: string): int

参数:

  • 命令:要执行的系统命令(字符串类型)

返回值:

  • 命令退出码(整数类型)

sii.execOut()

执行系统命令并获取输出。

语法:

sii.execOut(命令: string): string

参数:

  • 命令:要执行的系统命令(字符串类型)

返回值:

  • 命令输出内容(字符串类型)

示例:

let exitCode: int = sii.exec("ls -la");
let output: string = sii.execOut("echo 'Hello World'");
sii.log("命令输出:" + output);

示例:

// 检查Git状态
let gitStatus: string = sii.execOut("git status --porcelain");
if (gitStatus.length > 0) {
sii.log("有未提交的更改");
} else {
sii.log("工作区干净");
}

JSON 处理

JSON 解析和序列化

sii.jsonParse()

解析JSON字符串为对象。

语法:

sii.jsonParse(json字符串: string): obj

参数:

  • json字符串:要解析的JSON字符串(字符串类型)

返回值:

  • 解析后的对象(对象类型)

sii.jsonStringify()

将对象序列化为JSON字符串。

语法:

sii.jsonStringify(对象: obj): string

参数:

  • 对象:要序列化的对象(对象类型)

返回值:

  • JSON字符串(字符串类型)

示例:

// 解析JSON字符串
let data: obj = sii.jsonParse(jsonString);

// 将对象序列化为JSON
let jsonString: string = sii.jsonStringify(data);

示例:

// 读取JSON配置文件
let configText: string = sii.readText("./config.json");
let config: obj = sii.jsonParse(configText);

// 处理配置数据
let appName: string = config.appName;
let port: int = config.port;

// 保存修改后的配置
let updatedConfig: obj = config;
updatedConfig.lastModified = sii.now();
let newConfigText: string = sii.jsonStringify(updatedConfig);
sii.writeText("./config.json", newConfigText);

数据库操作

提示

版本要求:以下功能从 v1.2.203 开始支持

Sii 语言提供了完整的数据库操作功能,支持 MySQL、PostgreSQL 和 SQLite 数据库。所有数据库操作都是异步的,会自动处理连接池和事务。

数据库连接

sii.db.connect()

连接数据库。

语法:

sii.db.connect(数据库类型: string, 配置对象: obj): void

参数:

  • 数据库类型:数据库类型,支持 "mysql""postgres"(或 "postgresql")、"sqlite"(或 "sqlite3"
  • 配置对象:数据库连接配置对象

配置对象字段:

MySQL/PostgreSQL 配置:

  • host:数据库主机地址(字符串类型)
  • port:数据库端口号(整数类型)
  • user:数据库用户名(字符串类型)
  • password:数据库密码(字符串类型)
  • database:数据库名称(字符串类型)

SQLite 配置:

  • filenamedatabase:数据库文件路径(字符串类型),默认为 :memory:(内存数据库)

返回值:

  • 无返回值(void)

示例:

// MySQL 连接配置
// Sii 不支持字面量的定义,需要将数据库配置信息写入对象中
class DbConfig {
host: string
port: int
user: string
password: string
database: string
}

crob dbConfig = new DbConfig(); // 创建配置对象
// 将配置信息写入对象
dbConfig.host = "localhost";
dbConfig.port = 3306;
dbConfig.user = "root";
dbConfig.password = "";
dbConfig.database = "sii_test";
// 执行连接
sii.db.connect("mysql", dbConfig);

示例:

// PostgreSQL 连接
crob pgConfig = new DbConfig();
pgConfig.host = "localhost";
pgConfig.port = 5432;
pgConfig.user = "postgres";
pgConfig.password = "password";
pgConfig.database = "mydb";

sii.db.connect("postgres", pgConfig);

示例:

// SQLite 连接
crob sqliteConfig = new DbConfig();
sqliteConfig.filename = "./data.db";

sii.db.connect("sqlite", sqliteConfig);

数据查询

sii.db.findOne()

查询单条记录。

语法:

sii.db.findOne(表名: string, 查询条件: obj): obj

参数:

  • 表名:要查询的表名(字符串类型)
  • 查询条件:查询条件对象(对象类型),可选

返回值:

  • 查询到的记录对象,如果未找到则返回 null

示例:

// 根据 ID 查询
crob condition = new User();
condition.id = 1;
let user: obj = sii.db.findOne("users", condition);
if (user) {
print("找到用户: " + user.name);
} else {
print("未找到用户");
}

sii.db.find()

查询多条记录。

语法:

sii.db.find(表名: string, 查询条件: obj): arr

参数:

  • 表名:要查询的表名(字符串类型)
  • 查询条件:查询条件对象(对象类型),可选。如果不提供,则查询所有记录

返回值:

  • 查询到的记录数组

示例:

// 查询所有用户
let allUsers: arr = sii.db.find("users");
print("用户总数: " + sii.length(allUsers).toString());

// 根据条件查询
crob condition = new User();
condition.age = 25;
let users: arr = sii.db.find("users", condition);

查询条件支持的操作符:

查询条件对象支持以下操作符(通过对象属性传递):

  • 等于:直接设置属性值

    crob condition = new User();
    condition.id = 1; // WHERE id = 1
  • 大于:$gt

    crob condition = new User();
    condition.age = { $gt: 18 }; // WHERE age > 18
  • 小于:$lt

    condition.age = { $lt: 65 };  // WHERE age < 65
  • 大于等于:$gte

    condition.age = { $gte: 18 };  // WHERE age >= 18
  • 小于等于:$lte

    condition.age = { $lte: 65 };  // WHERE age <= 65
  • 不等于:$ne

    condition.status = { $ne: "deleted" };  // WHERE status != 'deleted'
  • IN 查询:$in

    condition.id = { $in: [1, 2, 3] };  // WHERE id IN (1, 2, 3)
  • LIKE 查询:$like

    condition.name = { $like: "%John%" };  // WHERE name LIKE '%John%'

数据插入

sii.db.insert()

插入数据。

语法:

sii.db.insert(表名: string, 数据对象: obj): obj

参数:

  • 表名:要插入数据的表名(字符串类型)
  • 数据对象:要插入的数据对象(对象类型)

返回值:

  • 插入后的数据对象,包含自动生成的主键 ID(如果存在)

示例:

// 定义用户模型
class User {
id: int
name: string
email: string
age: int
}

// 插入新用户
crob newUser = new User();
newUser.name = "John";
newUser.email = "john@example.com";
newUser.age = 25;
let insertedUser: obj = sii.db.insert("users", newUser);
print("插入用户,ID: " + insertedUser.id.toString());

数据更新

sii.db.update()

更新数据。

语法:

sii.db.update(表名: string, 查询条件: obj, 更新数据: obj): void

参数:

  • 表名:要更新数据的表名(字符串类型)
  • 查询条件:更新条件对象(对象类型)
  • 更新数据:要更新的数据对象(对象类型)

返回值:

  • 无返回值(void)

示例:

// 更新用户年龄
crob condition = new User();
condition.id = 1;
crob updateData = new User();
updateData.age = 26;
sii.db.update("users", condition, updateData);
print("已更新用户 ID 1 的年龄为 26");

数据删除

sii.db.delete()

删除数据。

语法:

sii.db.delete(表名: string, 查询条件: obj): void

参数:

  • 表名:要删除数据的表名(字符串类型)
  • 查询条件:删除条件对象(对象类型)

返回值:

  • 无返回值(void)

示例:

// 删除用户
crob condition = new User();
condition.id = 3;
sii.db.delete("users", condition);
print("已删除用户 ID 3");

原始 SQL 查询

sii.db.query()

执行原始 SQL 查询。

语法:

sii.db.query(SQL语句: string, 参数数组: arr): arr

参数:

  • SQL语句:要执行的 SQL 语句(字符串类型),支持参数占位符 ?
  • 参数数组:SQL 参数数组(数组类型),可选

返回值:

  • 查询结果数组,格式为 [rows, fields](MySQL)或 [rows, result](PostgreSQL)

示例:

// 执行原始 SQL
let result: arr = sii.db.query("SELECT * FROM users WHERE age > ?", [18]);
let rows: arr = result[0];
print("查询到 " + sii.length(rows).toString() + " 条记录");

事务处理

sii.db.transaction()

执行事务操作。

语法:

sii.db.transaction(回调函数: func): void

参数:

  • 回调函数:事务中要执行的函数(函数类型),函数内部的所有数据库操作会在同一个事务中执行

返回值:

  • 无返回值(void)

说明:

  • 如果回调函数执行成功,事务会自动提交
  • 如果回调函数抛出错误,事务会自动回滚

示例:

func transferMoney(fromId: int, toId: int, amount: int): void {
sii.db.transaction(() => {
// 扣除发送方余额
crob fromCondition = new Account();
fromCondition.id = fromId;
crob fromUpdate = new Account();
fromUpdate.balance = { $gt: amount }; // 确保余额足够
sii.db.update("accounts", fromCondition, { balance: balance - amount });

// 增加接收方余额
crob toCondition = new Account();
toCondition.id = toId;
crob toUpdate = new Account();
toUpdate.balance = balance + amount;
sii.db.update("accounts", toCondition, toUpdate);
});
}

查询构建器

sii.db.table()

使用链式查询构建器。

语法:

sii.db.table(表名: string): obj

返回值:

  • 查询构建器对象,支持链式调用

构建器方法:

  • where(字段名: string, 操作符: string, 值: any):添加 WHERE 条件
  • join(表名: string, 字段1: string, 字段2: string):添加 JOIN
  • orderBy(字段名: string, 方向: string):添加排序(方向:"ASC""DESC"
  • limit(数量: int):限制返回数量
  • find():执行查询,返回数组
  • findOne():执行查询,返回单条记录

示例:

// 使用查询构建器
let users: arr = sii.db.table("users")
.where("age", ">", 18)
.where("status", "=", "active")
.orderBy("created_at", "DESC")
.limit(10)
.find();

连接管理

sii.db.close()

关闭数据库连接。

语法:

sii.db.close(): void

参数:

  • 无参数

返回值:

  • 无返回值(void)

说明:

  • 关闭数据库连接池
  • 程序执行完毕后会自动调用,通常不需要手动调用

完整示例

// 定义数据库配置类
class DbConfig {
host: string
port: int
user: string
password: string
database: string
}

// 创建配置对象
crob dbConfig = new DbConfig();
dbConfig.host = "localhost";
dbConfig.port = 3306;
dbConfig.user = "root";
dbConfig.password = "";
dbConfig.database = "sii_test";

// 连接数据库
sii.db.connect("mysql", dbConfig);

// 定义用户模型
class User {
id: int
name: string
email: string
age: int
}

// 插入数据
crob newUser1 = new User();
newUser1.name = "John";
newUser1.email = "john@example.com";
newUser1.age = 25;
let insertedUser1: obj = sii.db.insert("users", newUser1);
print("插入用户1,ID: " + insertedUser1.id.toString());

crob newUser2 = new User();
newUser2.name = "Alice";
newUser2.email = "alice@example.com";
newUser2.age = 30;
let insertedUser2: obj = sii.db.insert("users", newUser2);
print("插入用户2,ID: " + insertedUser2.id.toString());

// 查询数据
// 查询单个用户
crob queryCondition = new User();
queryCondition.id = 1;
let user: obj = sii.db.findOne("users", queryCondition);
if (user) {
print("查询到用户: " + user.name + ", 邮箱: " + user.email + ", 年龄: " + user.age.toString());
} else {
print("未找到用户");
}

// 查询所有用户
let allUsers: arr = sii.db.find("users");
print("所有用户数量: " + sii.length(allUsers).toString());

// 更新数据
crob updateCondition = new User();
updateCondition.id = 1;
crob updateData = new User();
updateData.age = 26;
sii.db.update("users", updateCondition, updateData);
print("已更新用户 ID 1 的年龄为 26");

// 删除数据
crob deleteCondition = new User();
deleteCondition.id = 2;
sii.db.delete("users", deleteCondition);
print("已删除用户 ID 2");

数据库驱动安装

在使用数据库功能前,需要安装相应的数据库驱动:

MySQL:

npm install mysql2

PostgreSQL:

npm install pg

SQLite:

npm install sqlite3 sqlite

注意事项

  1. 异步操作:所有数据库操作都是异步的,会自动处理 await
  2. 连接管理:程序执行完毕后会自动关闭数据库连接
  3. 参数化查询:使用参数化查询防止 SQL 注入攻击
  4. 事务支持:使用 sii.db.transaction() 确保数据一致性
  5. 错误处理:数据库操作失败时会抛出错误,需要适当的错误处理
  6. 类型安全:建议使用类定义数据模型,确保类型安全

HTTP 服务

服务器创建

sii.listen()

启动HTTP服务器。

语法:

sii.listen(端口号: int): void

参数:

  • 端口号:服务器监听的端口号(整数类型)

返回值:

  • 无返回值(void)

路由定义

sii.get()

定义GET路由。

语法:

sii.get(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

sii.post()

定义POST路由。

语法:

sii.post(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

sii.put()

定义PUT路由。

语法:

sii.put(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

sii.delete()

定义DELETE路由。

语法:

sii.delete(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

sii.options()

定义OPTIONS路由。

语法:

sii.options(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

sii.head()

定义HEAD路由。

语法:

sii.head(路径: string, 处理函数名: string): void

参数:

  • 路径:路由路径(字符串类型)
  • 处理函数名:处理函数的名称(字符串类型)

返回值:

  • 无返回值(void)

响应处理

sii.respText()

返回文本响应。

语法:

sii.respText(响应对象: obj, 文本内容: string): void

参数:

  • 响应对象:HTTP响应对象(对象类型)
  • 文本内容:要返回的文本内容(字符串类型)

返回值:

  • 无返回值(void)

sii.respJson()

返回JSON响应。

语法:

sii.respJson(响应对象: obj, 数据对象: obj): void

参数:

  • 响应对象:HTTP响应对象(对象类型)
  • 数据对象:要返回的数据对象(对象类型)

返回值:

  • 无返回值(void)

sii.respHtml()

返回HTML响应。

语法:

sii.respHtml(响应对象: obj, HTML内容: string): void

参数:

  • 响应对象:HTTP响应对象(对象类型)
  • HTML内容:要返回的HTML内容(字符串类型)

返回值:

  • 无返回值(void)

完整示例:

// 定义处理函数
func handleHome(req: obj, res: obj): void {
sii.respText(res, "欢迎使用Sii HTTP服务!");
}

func handleApi(req: obj, res: obj): void {
let data: obj = {
message: "Hello from Sii API",
timestamp: sii.now()
};
sii.respJson(res, data);
}

func handleUserUpdate(req: obj, res: obj): void {
let userId: string = req.params.id;
let userData: obj = req.body;
sii.log("更新用户 " + userId + ": " + sii.jsonStringify(userData));
sii.respJson(res, { success: true, message: "用户更新成功" });
}

func handleUserDelete(req: obj, res: obj): void {
let userId: string = req.params.id;
sii.log("删除用户: " + userId);
sii.respJson(res, { success: true, message: "用户删除成功" });
}

func handleOptions(req: obj, res: obj): void {
sii.respText(res, "CORS预检请求");
}

func handleHead(req: obj, res: obj): void {
// HEAD请求通常不返回响应体,只返回状态码和头部
sii.respText(res, "");
}

// 定义路由
sii.get("/", "handleHome");
sii.get("/api/hello", "handleApi");
sii.put("/api/users/:id", "handleUserUpdate");
sii.delete("/api/users/:id", "handleUserDelete");
sii.options("/api/*", "handleOptions");
sii.head("/api/status", "handleHead");

// 启动服务器
sii.listen(3000);
sii.log("服务器启动在端口 3000");

日志记录

日志函数

sii.log()

记录普通日志信息。

语法:

sii.log(信息内容: string): void

参数:

  • 信息内容:要记录的日志信息(字符串类型)

返回值:

  • 无返回值(void)

sii.warn()

记录警告日志信息。

语法:

sii.warn(警告内容: string): void

参数:

  • 警告内容:要记录的警告信息(字符串类型)

返回值:

  • 无返回值(void)

sii.error()

记录错误日志信息。

语法:

sii.error(错误内容: string): void

参数:

  • 错误内容:要记录的错误信息(字符串类型)

返回值:

  • 无返回值(void)

示例:

// 普通日志
sii.log("应用启动成功");

// 警告日志
sii.warn("配置文件不存在,使用默认配置");

// 错误日志
sii.error("数据库连接失败");

示例:

func processData(data: string): void {
sii.log("开始处理数据");

if (data.length == 0) {
sii.warn("数据为空,跳过处理");
back;
}

// 处理逻辑
sii.log("数据处理完成");
}

// 错误处理
func handleError(error: string): void {
sii.error("处理失败:" + error);
}

完整应用示例

文件处理工具

func processFiles(): void {
let inputDir: string = "./input";
let outputDir: string = "./output";

// 确保输出目录存在
if (!sii.exists(outputDir)) {
sii.mkdirs(outputDir);
sii.log("创建输出目录");
}

// 处理文件(简化示例)
let files: arr = ["file1.txt", "file2.txt", "file3.txt"];

forloop (let i: int = 0; i < 3; i.toUp(1)) {
let filename: string = files[i];
let inputPath: string = sii.pathJoin(inputDir, filename);
let outputPath: string = sii.pathJoin(outputDir, "processed_" + filename);

if (sii.exists(inputPath)) {
let content: string = sii.readText(inputPath);
let processedContent: string = "处理后的内容:" + content;
sii.writeText(outputPath, processedContent);
sii.log("处理文件:" + filename);
} else {
sii.warn("文件不存在:" + filename);
}
}
}

// 执行文件处理
processFiles();

注意事项

  1. 命名空间:所有标准库函数都通过 sii. 前缀调用
  2. 类型安全:所有函数都有严格的类型检查
  3. 错误处理:文件操作等可能失败的操作需要适当的错误处理
  4. 性能考虑:频繁的文件I/O操作可能影响性能
  5. 安全性:执行系统命令时要注意安全性
  6. 跨平台:路径操作在不同操作系统上可能有差异

最佳实践

  1. 错误处理:在使用文件操作前检查文件是否存在
  2. 资源管理:及时关闭文件句柄和网络连接
  3. 日志记录:使用适当的日志级别记录信息
  4. 配置管理:将配置信息存储在JSON文件中
  5. 性能优化:避免在循环中进行重复的文件操作
  6. 安全考虑:验证用户输入,避免路径遍历攻击

通过标准库,Sii 语言提供了完整的系统编程能力,支持从简单的脚本到复杂的Web应用开发。