Swift: Swift 扩展与访问控制：extension 和访问级别完全指南

func timeAgo(from date: Date) -> String {
    let seconds = Date().timeIntervalSince(date)
    if seconds < 60 { return "\(Int(seconds))s ago" }
    if seconds < 3600 { return "\(Int(seconds / 60))m ago" }
    return "\(Int(seconds / 3600))h ago"
}
// 每次都要传参调用
print(timeAgo(from: someDate))

extension Date {
    func timeAgo() -> String {
        let seconds = Date().timeIntervalSince(self)
        if seconds < 60 { return "\(Int(seconds))s ago" }
        if seconds < 3600 { return "\(Int(seconds / 60))m ago" }
        return "\(Int(seconds / 3600))h ago"
    }
}
// 看起来就像 Date 自带的方法
print(someDate.timeAgo())

// ============================================
// 为 String 添加实用扩展
// ============================================
extension String {
    // 计算属性——是否为有效的邮箱
    var isValidEmail: Bool {
        return contains("@") && contains(".")
    }
    // 方法——截取前 N 个字符
    func prefix(_ maxLength: Int) -> String {
        guard count > maxLength else { return self }
        return String(self.prefix(maxLength)) + "..."
    }
    // 方法——反转字符串
    func reversed() -> String {
        return String(self.reversed())
    }
}
let email = "alice@example.com"
print("\(email) is valid: \(email.isValidEmail)")
let longText = "This is a very long string that needs truncation"
print(longText.prefix(20))
print("Hello".reversed())

// ============================================
// 通过扩展遵守协议
// ============================================
// 1. 定义基础类型
struct User {
    let id: Int
    let name: String
    let email: String
}
// 2. 通过扩展遵守 Hashable（用于 Set 和 Dictionary 键）
extension User: Hashable {
    func hash(into hasher: inout Hasher) {
        hasher.combine(id)
    }
}
// 3. 通过扩展遵守 Equatable
extension User: Equatable {
    static func == (lhs: User, rhs: User) -> Bool {
        return lhs.id == rhs.id
    }
}
// 4. 使用
let users: Set<User> = [
    User(id: 1, name: "Alice", email: "alice@example.com"),
    User(id: 1, name: "Alice", email: "alice@example.com"),  // 重复——被去重
    User(id: 2, name: "Bob", email: "bob@example.com")
]
print("Users count: \(users.count)")  // 2

// ============================================
// 五种访问级别的使用
// ============================================
// 公开给所有模块使用的类
public class BankAccount {
    // 对外只读，对内可写
    public private(set) var balance: Double
    // 私有字段——仅当前类可访问
    private var accountNumber: String
    private var transactionHistory: [String] = []
    // 文件内可访问——用于日志
    fileprivate var lastTransactionDate: Date?
    // 模块内可访问——用于内部审计
    internal var branchCode: String
    public init(accountNumber: String, balance: Double, branchCode: String) {
        self.accountNumber = accountNumber
        self.balance = balance
        self.branchCode = branchCode
    }
    public func deposit(amount: Double) {
        balance += amount
        transactionHistory.append("Deposit: \(amount)")
        lastTransactionDate = Date()
    }
    // 私有辅助方法
    private func log(_ message: String) {
        print("[Private] \(message)")
    }
}
let account = BankAccount(accountNumber: "123-456", balance: 1000, branchCode: "BR-001")
print("Balance: \(account.balance)")    // public getter 可读
// account.balance = 2000               // 编译错误！public private(set) 不让外部写
// print(account.accountNumber)         // 编译错误！private 属性
// print(account.lastTransactionDate)   // 编译错误！fileprivate，不同文件不可访问
print("Branch: \(account.branchCode)")  // internal 同模块可访问

// ============================================
// private 在 extension 中的可见性
// ============================================
struct UserAccount {
    private var token: String = "secret-token"
    let name: String
    func getToken() -> String {
        return token
    }
}
// 同一文件中的 extension 可以访问 private 成员
extension UserAccount {
    func resetToken() {
        token = "new-token"  // 可以访问！同一文件中
    }
}
var account = UserAccount(name: "Alice")
print(account.getToken())
account.resetToken()
print(account.getToken())

// 核心数据定义
struct Product {
    let id: Int
    let name: String
    let price: Double
}
// MARK: - 遵守 Equatable
extension Product: Equatable {
    static func == (lhs: Product, rhs: Product) -> Bool {
        return lhs.id == rhs.id
    }
}
// MARK: - 遵守 Codable
extension Product: Codable { }
// MARK: - 工具方法
extension Product {
    func formattedPrice() -> String {
        return "$\(String(format: "%.2f", price))"
    }
    var priceWithTax: Double {
        return price * 1.08
    }
}

// ============================================
// 扩展添加嵌套类型与便利初始化器
// ============================================
// 基础类型
struct Book {
    let title: String
    let author: String
    let year: Int
}
// 扩展：添加嵌套类型和便利初始化器
extension Book {
    // 嵌套枚举——分类
    enum Genre: String {
        case fiction = "小说"
        case nonfiction = "非小说"
        case science = "科学"
        case history = "历史"
    }
    // 嵌套结构体——阅读统计
    struct ReadingStats {
        var pagesRead: Int
        var totalPages: Int
        var progress: Double {
            totalPages > 0 ? Double(pagesRead) / Double(totalPages) * 100 : 0
        }
    }
    // 便利初始化器——从 JSON 字典创建
    init?(from dict: [String: Any]) {
        guard let title = dict["title"] as? String,
              let author = dict["author"] as? String,
              let year = dict["year"] as? Int else {
            return nil
        }
        self.init(title: title, author: author, year: year)
    }
}
// 使用
let book1 = Book(title: "Swift 编程", author: "Apple", year: 2024)
let genre = Book.Genre.science
print("\(book1.title) - 分类：\(genre.rawValue)")
let stats = Book.ReadingStats(pagesRead: 120, totalPages: 350)
print("阅读进度：\(String(format: "%.1f", stats.progress))%")
// 从字典创建
let dict = ["title": "Swift 进阶", "author": "Alice", "year": 2025] as [String: Any]
if let book2 = Book(from: dict) {
    print("从字典创建：\(book2.title) (\(book2.author), \(book2.year))")
}

// ============================================
// 完整示例：用户管理系统
// 功能：extension + 访问控制综合运用
// ============================================
import Foundation
// 1. 核心用户类型
public class User {
    public let id: Int
    public let name: String
    public let email: String
    // 对外只读，对内可写
    public private(set) var score: Int = 0
    public private(set) var isActive: Bool = true
    // 模块内部可访问
    internal var lastLogin: Date?
    // 私有
    private var loginHistory: [Date] = []
    public init(id: Int, name: String, email: String) {
        self.id = id
        self.name = name
        self.email = email
    }
    public func login() {
        let now = Date()
        lastLogin = now
        loginHistory.append(now)
        isActive = true
    }
    public func addScore(_ points: Int) {
        // 内部校验
        guard points > 0 else { return }
        score += points
    }
}
// MARK: - 描述信息扩展
extension User {
    public func description() -> String {
        return "User(\(id): \(name), score: \(score), active: \(isActive))"
    }
    // 根据最后登录时间判断
    public var isOnline: Bool {
        guard let last = lastLogin else { return false }
        return Date().timeIntervalSince(last) < 300
    }
}
// MARK: - 活动日志扩展
extension User {
    // fileprivate——仅本文件可访问
    fileprivate func generateActivityReport() -> String {
        return """
        User Report - \(name)
        =================
        Score: \(score)
        Active: \(isActive)
        Last Login: \(lastLogin?.description ?? "Never")
        """
    }
    public func printReport() {
        print(generateActivityReport())
    }
}
// 3. 使用示例
let user = User(id: 1, name: "Alice", email: "alice@example.com")
user.login()
user.addScore(50)
user.addScore(30)
print(user.description())
print("Online: \(user.isOnline)")
user.printReport()
// user.score = 100        // 编译错误——public private(set)
// user.loginHistory        // 编译错误——private