标准库
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 配置:
filename或database:数据库文件路径(字符串类型),默认为: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 -
大于:
$gtcrob condition = new User();
condition.age = { $gt: 18 }; // WHERE age > 18 -
小于:
$ltcondition.age = { $lt: 65 }; // WHERE age < 65 -
大于等于:
$gtecondition.age = { $gte: 18 }; // WHERE age >= 18 -
小于等于:
$ltecondition.age = { $lte: 65 }; // WHERE age <= 65 -
不等于:
$necondition.status = { $ne: "deleted" }; // WHERE status != 'deleted' -
IN 查询:
$incondition.id = { $in: [1, 2, 3] }; // WHERE id IN (1, 2, 3) -
LIKE 查询:
$likecondition.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):添加 JOINorderBy(字段名: 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
注意事项
- 异步操作:所有数据库操作都是异步的,会自动处理
await - 连接管理:程序执行完毕后会自动关闭数据库连接
- 参数化查询:使用参数化查询防止 SQL 注入攻击
- 事务支持:使用
sii.db.transaction()确保数据一致性 - 错误处理:数据库操作失败时会抛出错误,需要适当的错误处理
- 类型安全:建议使用类定义数据模型,确保类型安全
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();
注意事项
- 命名空间:所有标准库函数都通过
sii.前缀调用 - 类型安全:所有函数都有严格的类型检查
- 错误处理:文件操作等可能失败的操作需要适当的错误处理
- 性能考虑:频繁的文件I/O操作可能影响性能
- 安全性:执行系统命令时要注意安全性
- 跨平台:路径操作在不同操作系统上可能有差异
最佳实践
- 错误处理:在使用文件操作前检查文件是否存在
- 资源管理:及时关闭文件句柄和网络连接
- 日志记录:使用适当的日志级别记录信息
- 配置管理:将配置信息存储在JSON文件中
- 性能优化:避免在循环中进行重复的文件操作
- 安全考虑:验证用户输入,避免路径遍历攻击
通过标准库,Sii 语言提供了完整的系统编程能力,支持从简单的脚本到复杂的Web应用开发。