Instruction file imported from 13662049573/TFYSwiftMacOSAppKit_Swift (.cursor/rules/swift-language-style.mdc). Copyright stays with the author.

Swift 语言与风格规则

命名

• 类型、协议、枚举：大驼峰 ViewController, UserService, NetworkError。
• 变量、函数、参数：小驼峰 userName, fetchUser(), maxCount。
• 常量：小驼峰；若为类型级常量，可用 static let 并保持语义清晰。
• 布尔：使用 is, has, should, can 等前缀，如 isEnabled, hasContent。
• 缩写：仅保留首字母大写（如 url, id），多字母缩写如 URL 全大写。

类型与可选值

• 优先使用值类型（struct、enum）；需要引用语义或继承时再用 class。
• 避免强制解包 !；使用 if let、guard let、?? 或 optional.map。
• 仅在 API 明确保证非空（如 @MainActor 下 UI 属性）或类型系统已表达非空时使用隐式解包。
• 使用 Result<Success, Failure> 或 throws 表达可能失败的操作，避免用可选值表示错误。

错误处理

• 自定义错误遵循 Error 并尽量用 enum 表达错误种类。
• 异步代码优先使用 async throws；在合适层级捕获并转换错误，避免静默吞掉。
• 对外 API 用文档或类型明确标注可能抛出的错误与前置条件。

协议与泛型

• 协议命名：能力用形容词（Equatable, Sendable），角色用名词（DataSource）。
• 使用 some Protocol 或泛型约束表达“某实现”而非“任意类型”，提高可读性与性能。
• 泛型约束写清楚（where 或 <T: Protocol>），避免过度抽象。

示例（风格）

// 推荐：值类型 + 明确错误
struct User {
    let id: UUID
    var displayName: String
}

enum NetworkError: Error {
    case invalidURL
    case httpStatus(Int)
}

func loadUser(id: UUID) async throws -> User { ... }

// 避免：强制解包、用可选表示错误
var url: URL!  // 不推荐
func loadUser() -> User?  // 失败时用 Result 或 throws 更清晰