跳到主要内容

Sii库编写规范

本文档详细介绍了如何编写高质量的Sii库，包括代码规范、文档要求、版本管理等最佳实践。

目录​

库类型限制​

支持的功能性库​

库中心仅支持功能性代码库，包括：

  • 数学计算库 - 提供数学函数和算法
  • 数据处理库 - 提供数据操作和转换功能
  • 工具函数库 - 提供通用工具和辅助函数
  • 算法库 - 提供各种算法实现
  • 系统接口库 - 提供系统级功能接口

不支持的库类型​

库中心不支持以下类型的库：

  • SiiUI Web代码 - 包含UI组件和Web界面的代码
  • 样式和主题库 - CSS、样式相关的代码
  • Web应用代码 - 完整的Web应用程序

库内容要求​

上传的库必须：

  • ✅ 包含纯功能性代码
  • ✅ 提供可复用的函数和类
  • ✅ 使用share关键字共享所有对外函数
  • ✅ 不依赖特定的UI框架
  • ✅ 可以在任何Sii环境中使用
  • ❌ 不包含UI组件定义
  • ❌ 不包含Web界面代码
  • ❌ 不包含样式和布局代码

函数共享要求​

重要：库中的所有对外函数必须使用share关键字：

// ✅ 正确：使用share共享函数
share func add(a: int, b: int): int {
    back a + b;
}

// ❌ 错误：没有share的函数无法被外部调用
func internalHelper(x: int): int {
    back x * 2;
}
  • 没有share的函数只能在库内部使用
  • 只有share的函数才能被外部调用
  • 使用share控制方法的访问权限

详细语法：关于 share 关键字的具体用法，请参考 模块与引用文档。

库依赖管理​

重要：如果库引用了其他库，必须在文件开头注释说明：

/*
 * 库依赖说明：
 * - math-utils v1.2.0: 提供基础数学运算
 * - string-utils v2.1.0: 提供字符串处理功能
 * - data-utils v1.0.5: 提供数据处理功能
 */

// 引用其他库
cite { math } from lib.math-utils;
cite { strin } from lib.string-utils;

// 库的主要功能
share func complexCalculation(x: int, y: int): int {
    let result = math.add(x, y);
    back result;
}

依赖注释要求：

  • 必须在文件开头使用多行注释说明
  • 必须包含库名称和具体版本号
  • 必须说明每个依赖库的用途
  • 便于其他开发者了解库的依赖关系

详细引用语法：关于 cite 关键字的具体用法和语法，请参考 模块与引用文档。

功能性库编写指南​

数学计算库示例​

// math-utils.sii - 数学工具库
// 注意：所有对外函数都必须使用share关键字

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

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

share func power(base: int, exp: int): int {
    // 计算幂运算
    back base ^ exp;
}

// 内部辅助函数（不需要share）
func validateNumber(num: int): bool {
    back num >= 0;
}

数据处理库示例​

// data-utils.sii - 数据处理库
// 所有对外函数都使用share关键字

share func getArrayLength(arr: arr): int {
    back arr.length;
}

share func getFirstItem(arr: arr): unknown {
    if (arr.length > 0) {
        back arr[0];
    }
    back null;
}

share func isEmpty(arr: arr): bool {
    back arr.length == 0;
}

工具函数库示例​

// string-utils.sii - 字符串工具库
// 所有对外函数都使用share关键字

share func getStringLength(str: string): int {
    back str.length;
}

share func toUpperCase(str: string): string {
    back str.toUpperCase();
}

share func contains(str: string, substring: string): bool {
    back str.contains(substring);
}

算法库示例​

// algorithms.sii - 算法库
// 所有对外函数都使用share关键字

share func findMax(arr: arr): int {
    let max = arr[0];
    forloop (let i = 1; i < arr.length; i = i + 1) {
        if (arr[i] > max) {
            max = arr[i];
        }
    }
    back max;
}

详细语法：关于 forloop 循环的用法，请参考 控制流程文档。

share func findMin(arr: arr): int {
    let min = arr[0];
    forloop (let i = 1; i < arr.length; i = i + 1) {
        if (arr[i] < min) {
            min = arr[i];
        }
    }
    back min;
}

库基本结构​

简化库结构​

your-library/
├── README.md              # 库说明文档
└── your-library.sii      # 库的主要代码文件

必需文件​

每个Sii库只需要包含以下文件：

  • README.md - 库的基本介绍和使用说明
  • your-library.sii - 库的主要代码文件

库文件命名​

  • 库文件名应该与库名一致
  • 使用小写字母和连字符：math-utils.sii
  • 避免使用下划线或驼峰命名

命名规范​

库名规范​

  • 使用小写字母和连字符：my-awesome-library
  • 避免使用下划线或驼峰命名
  • 名称应具有描述性，能清楚表达库的功能
  • 避免与现有库重名

函数命名​

// ✅ 推荐：使用动词开头，描述功能
func calculateArea(width: int, height: int): int {
    back width * height;
}

// ✅ 推荐：布尔函数使用is/has/can开头
func isValidEmail(email: string): bool {
    back email.contains("@");
}

// ✅ 推荐：数组操作函数使用动词
func addItem(item: int): void {
    push item: int => items[0];
}

// ❌ 避免：命名不清晰
func calc(w: int, h: int): int {
    back w * h;
}

变量命名​

// ✅ 推荐：使用有意义的名称
let userCount: int = 0;
let isUserLoggedIn: bool = false;
let currentUserName: string = "";

// ❌ 避免：使用缩写或无意义名称
let cnt: int = 0;
let flag: bool = false;
let str: string = "";

类命名​

// ✅ 推荐：使用PascalCase
class UserManager {
    // 类定义
}

class DataProcessor {
    // 类定义
}

// ❌ 避免：使用小写或下划线
class user_manager {
    // 类定义
}

详细语法：关于类的定义和使用，请参考 面向对象编程文档。

代码规范​

缩进和格式​

// ✅ 推荐：使用4个空格缩进
func calculateSum(a: int, b: int): int {
    let result: int = a + b;
    back result;
}

类型注解​

// ✅ 推荐：明确指定类型
func addNumbers(a: int, b: int): int {
    back a + b;
}

// ✅ 推荐：简单类定义
class User {
    name: string;
    age: int;
}

详细语法：关于Sii语言的数据类型和类型注解，请参考 数据类型文档。

错误处理​

// ✅ 推荐：适当的错误处理
func divide(a: int, b: int): int {
    if (b == 0) {
        print("错误：除数不能为零");
        back 0;
    }
    back a / b;
}

详细语法：关于条件语句和错误处理，请参考 控制流程文档。

注释规范​

// 单行注释：描述函数功能
func calculateSum(a: int, b: int): int {
    let sum: int = a + b;
    back sum;
}

/*
 * 多行注释：详细说明函数用途
 * 这个函数计算两个数的和
 */
func add(a: int, b: int): int {
    back a + b;
}

文档要求​

README.md 模板​

# 库名称

简短描述库的功能和用途。

## 安装

```bash
sii install 库名称

快速开始​

cite "库名称" from "库名称.sii";

// 基本使用示例
let result = calculateArea(10, 20);
print(result);

API 文档​

函数名​

参数：

  • param1: type - 参数描述
  • param2: type - 参数描述

返回值： type - 返回值描述

示例：

let result = functionName(param1, param2);

许可证​

MIT License


### 代码注释

```sii
/**
 * 计算两个数的和
 * @param a 第一个数
 * @param b 第二个数
 * @returns 两数之和
 */
func add(a: int, b: int): int {
    back a + b;
}

/**
 * 用户管理类
 * 提供用户注册、登录、信息管理等功能
 */
class UserManager {
    private users: arr = [];
    
    /**
     * 注册新用户
     * @param userData 用户数据
     * @returns 注册是否成功
     */
    func registerUser(userData: obj): bool {
        // 实现逻辑
        back true;
    }
}

最佳实践​

性能优化​

// ✅ 推荐：缓存重复计算的值
func calculateSum(a: int, b: int): int {
    let result: int = a + b;
    back result;
}

内存管理​

// ✅ 推荐：及时清理资源
func processData(data: string): string {
    let result: string = data;
    // 处理完成后及时清理
    back result;
}

错误处理​

// ✅ 推荐：提供有意义的错误信息
func validateEmail(email: string): bool {
    if (email.length == 0) {
        print("邮箱地址不能为空");
        back false;
    }
    
    if (!email.contains("@")) {
        print("邮箱地址格式不正确");
        back false;
    }
    
    back true;
}

数组操作最佳实践​

// ✅ 推荐：安全的数组操作
func getArrayLength(arr: arr): int {
    if (arr != null) {
        back arr.length;
    }
    back 0;
}

详细语法：关于数组的操作和语句，请参考 数组与语句文档。

函数设计原则​

// ✅ 推荐：单一职责原则
func calculateArea(width: int, height: int): int {
    back width * height;
}

func calculatePerimeter(width: int, height: int): int {
    back 2 * (width + height);
}

模块化设计​

// ✅ 推荐：按功能分组
// math.sii - 数学函数
share func add(a: int, b: int): int {
    back a + b;
}

// string.sii - 字符串函数
share func getLength(str: string): int {
    back str.length;
}

常见问题​

Q: 如何处理向后兼容性？​

A: 在添加新功能时，确保不破坏现有API。如果需要重大更改，考虑创建新的主版本。

Q: 库的大小限制是多少？​

A: 建议单个库文件不超过1MB，总库大小不超过10MB。

Q: 如何处理依赖关系？​

A: 在 package.json 中明确声明所有依赖，避免循环依赖。

Q: 如何编写好的示例代码？​

A: 示例应该简洁明了，展示库的核心功能，包含必要的注释。

Q: 为什么不能上传SiiUI Web代码？​

A: 库中心专门用于功能性代码库，不支持UI相关代码。在编写SiiUI Web代码时可以调用库，方便开发者快速构建Web项目。

Q: 如何判断我的库是否符合要求？​

A: 检查以下几点：

  • 库是否只包含纯功能性代码？
  • 是否不依赖特定的UI框架？
  • 是否可以在任何Sii环境中使用？
  • 是否提供了可复用的函数和类？
  • 是否所有对外函数都使用了share关键字？

Q: 为什么必须使用share关键字？​

A: share关键字是Sii库系统的核心机制：

  • 没有share的函数只能在库内部使用
  • 只有share的函数才能被外部调用
  • 使用share可以控制方法的访问权限
  • 这是库编写的基本要求

Q: 如何正确引用其他库？​

A: 引用其他库时需要遵循以下规范：

  • 在文件开头使用多行注释说明所有依赖库
  • 必须包含库名称和具体版本号
  • 说明每个依赖库的用途
  • 使用cite语句引用库文件
  • 便于其他开发者了解依赖关系

Q: 如果我的库包含UI代码怎么办？​

A: 将功能性代码和UI代码分离：

  • 功能性代码可以上传到库中心
  • UI代码应该放在其他专门的平台
  • 在库的文档中说明UI代码的位置

总结​

遵循这些规范将帮助您创建高质量、易维护的Sii库。记住，好的库不仅仅是功能正确，还要易于理解、使用和维护。

重要提醒：

  • 所有对外函数必须使用share关键字
  • 没有share的函数无法被外部调用
  • 使用share控制方法的访问权限
  • 引用其他库时必须在文件开头注释说明依赖关系
  • 必须包含库名称和具体版本号
  • 这是库编写的基本要求

Sii语言具有独特的语法特性，如 back 语句、esle if 条件、forloop 循环、数组操作语句等，在编写库时要充分利用这些特性，同时保持代码的可读性和一致性。

如有疑问，请参考官方文档。