microwind/ai-skills/encapsulation-principle

// ❌ 缺乏封装：内部状态暴露
public class BankAccount {
    public double balance;      // 公开字段
    public List<Transaction> transactions;  // 公开集合
 
    // 任何人都可以直接修改余额
    // account.balance = -1000;  合法但错误！
}
 
// ✅ 良好封装
public class BankAccount {
    private double balance;
    private final List<Transaction> transactions = new ArrayList<>();
 
    public BankAccount(double initialBalance) {
        if (initialBalance < 0) throw new IllegalArgumentException("初始余额不能为负");
        this.balance = initialBalance;
    }
 
    public void deposit(double amount) {
        if (amount <= 0) throw new IllegalArgumentException("存款金额必须为正");
        this.balance += amount;
        transactions.add(new Transaction(TransactionType.DEPOSIT, amount));
    }
 
    public void withdraw(double amount) {
        if (amount <= 0) throw new IllegalArgumentException("取款金额必须为正");
        if (amount > balance) throw new InsufficientFundsException();
        this.balance -= amount;
        transactions.add(new Transaction(TransactionType.WITHDRAWAL, amount));
    }
 
    public double getBalance() { return balance; }
 
    public List<Transaction> getTransactions() {
        return Collections.unmodifiableList(transactions);  // 返回不可变视图
    }
}

# ✅ Python 封装
class ShoppingCart:
    def __init__(self):
        self._items: list[CartItem] = []  # 受保护
    def add_item(self, product, quantity: int):
        if quantity <= 0:
            raise ValueError("数量必须为正")
        existing = self._find_item(product.id)
        if existing:
            existing.quantity += quantity
        else:
            self._items.append(CartItem(product, quantity))
    def remove_item(self, product_id: str):
        self._items = [i for i in self._items if i.product.id != product_id]
    @property
    def total(self) -> float:
        return sum(i.subtotal for i in self._items)
    @property
    def items(self) -> tuple:
        return tuple(self._items)  # 返回不可变副本
    def _find_item(self, product_id: str):
        return next((i for i in self._items if i.product.id == product_id), None)

// ❌ 1. 返回内部可变集合的引用
public List<Item> getItems() {
    return this.items;  // 外部可以直接修改！
}
 
// ✅ 返回不可变副本
public List<Item> getItems() {
    return Collections.unmodifiableList(this.items);
}
 
// ❌ 2. getter/setter 全部暴露 = 没有封装
public class User {
    private String name;
    private String email;
    private int age;
    // 为每个字段都生成 getter/setter = 等于公开字段
}
 
// ✅ 只暴露必要的操作
public class User {
    public void updateProfile(String name, String email) {
        validateEmail(email);
        this.name = name;
        this.email = email;
    }
}
 
// ❌ 3. 通过参数暴露内部结构
public void processOrder(Map<String, Object> orderData) {
    // 调用方需要知道 map 的 key 结构
}
 
// ✅ 使用类型化参数
public void processOrder(OrderRequest request) {
    // 结构明确，编译时检查
}