Peewee数据库框架中CompositeKey的正确使用方式

问题背景

在使用Python的Peewee ORM框架时，开发者可能会遇到需要定义复合主键的情况。复合主键是指由多个字段组合而成的主键，这在数据库设计中是常见的设计模式。然而，近期有开发者在使用Peewee的CompositeKey时遇到了一个特殊问题：当尝试将CompositeKey用于单个字段时，框架没有给出明确的错误提示，反而在后续操作中引发了难以理解的异常。

问题重现与分析

开发者报告了一个典型的使用场景：他们创建了两个模型类Item和ItemHistory，都继承自同一个基础模型BaseItem。其中ItemHistory正确地使用了两个字段作为复合主键，而Item则错误地尝试将单个字段third声明为CompositeKey。

class Item(BaseItem):
    class Meta:
        table_name = "item"
        primary_key = peewee.CompositeKey("third")  # 错误用法

这种用法导致了get_by_id()方法调用时抛出TypeError: 'int' object is not iterable异常。深入分析发现，这是因为CompositeKey内部实现假设总是处理多个字段的情况，当只有一个字段时，框架无法正确处理传入的ID值。

正确的解决方案

对于单字段主键的情况，Peewee提供了更直接和正确的方式：

class Item(BaseItem):
    third = peewee.IntegerField(primary_key=True)  # 正确用法
    class Meta:
        table_name = "item"

这种方式明确地将单个字段标记为主键，完全避免了使用CompositeKey带来的问题。这也是Peewee框架推荐的标准做法。

框架设计考量

从框架设计的角度来看，CompositeKey类本应只用于真正的复合主键场景（即两个或更多字段的组合）。当前的实现没有对单字段使用情况进行校验，这可以被视为框架的一个小缺陷。理想情况下，框架应该在模型定义时就检测并拒绝这种不合理的用法，而不是等到运行时才暴露问题。

最佳实践建议

1. 单字段主键：使用字段级别的primary_key=True参数
2. 真正的复合主键：才使用CompositeKey并传入多个字段名
3. 模型继承：注意基础模型中字段定义的继承关系
4. 错误处理：在自定义模型时，应该预先考虑主键设计的合理性

总结