Diesel中结构体字段顺序为何需与table!定义匹配？

问题现象 #

在Diesel中定义表和编写查询时，常遇到两类看似类型不匹配的错误：

• "the trait bound (_, _, ): CompatibleType<, DB> is not satisfied"
• "the trait bound : FromSql<, DB> is not satisfied"

这些错误的本质是结构体字段与table!宏定义的列顺序不一致。更危险的是，如果字段类型相同但顺序错误，编译不会报错，但会导致查询结果与结构体字段错位赋值，出现数据不匹配的问题。

示例代码如下：

use diesel::prelude::*;

table! {
    users {
        id -> Int4,
        name -> Text,
        favorite_number -> Int4,
    }
}

#[derive(Queryable)]
struct User {
    id: i32,
    favorite_number: i32,
    name: String,
}

fn get_users() -> Vec<User> {
    users::table.load::<User>(&mut get_connection()).unwrap()
}

对应的编译错误：

error[E0277]: the trait bound `(Integer, diesel::sql_types::Text, Integer): load_dsl::private::CompatibleType<User, Pg>` is not satisfied
    --> src/main.rs:19:31
     |
19   |     users::table.load::<User>(&mut get_connection()).unwrap()
     |                  ----         ^^^^^^^^^^^^^^^^^^^^^ the trait `load_dsl::private::CompatibleType<User, Pg>` is not implemented for `(Integer, diesel::sql_types::Text, Integer)`
     |                  |
     |                  required by a bound introduced by this call
     |
     = help: the following other types implement trait `load_dsl::private::CompatibleType<U, DB>`:
               (ST0,)
               (ST0, ST1)
               (ST0, ST1, ST2)
               (ST0, ST1, ST2, ST3)
               (ST0, ST1, ST2, ST3, ST4)
               (ST0, ST1, ST2, ST3, ST4, ST5)
               (ST0, ST1, ST2, ST3, ST4, ST5, ST6)
               (ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7)
             and 24 others
     = note: required for `users::table` to implement `LoadQuery<'_, _, User>`
note: required by a bound in `diesel::RunQueryDsl::load`
    --> /home/kmdreko/.cargo/registry/src/index.crates.io-6f17d22bba15001f/diesel-2.1.1/src/query_dsl/mod.rs:1543:15
     |
1541 |     fn load<'query, U>(self, conn: &mut Conn) -> QueryResult<Vec<U>>
     |        ---- required by a bound in this associated function
1542 |     where
1543 |         Self: LoadQuery<'query, Conn, U>,
     |               ^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `RunQueryDsl::load`

为什么字段顺序比名称更重要？ #

Diesel的设计核心是编译期类型安全，table!宏生成的查询会直接返回与列顺序对应的元组类型，而默认的Queryable trait是按结构体字段的声明顺序匹配元组元素，而非字段名称。

这种设计有两个关键原因：

1. 性能优化：按顺序匹配无需在运行期做字段名称的映射和查找，符合Rust零成本抽象的理念，避免额外运行时开销。
2. 编译期校验：通过类型系统直接校验元组元素与结构体字段的类型匹配，能在编译阶段发现大部分错误，规避运行时的类型兼容问题。

Diesel能否改用字段名称而非顺序匹配？ #

默认模式下是按顺序匹配，但可以通过派生宏属性开启名称匹配模式。在#[derive(Queryable)]时添加queryable_by_name属性，并指定对应数据库的backend，就能让结构体按字段名称与表列匹配：

#[derive(Queryable)]
#[diesel(queryable_by_name)]
#[diesel(check_for_backend(Pg))] // 对应PostgreSQL，其他数据库替换为Mysql/Sqlite
struct User {
    id: i32,
    favorite_number: i32,
    name: String,
}

需要注意：这种方式会引入少量运行时开销，且必须保证结构体字段名称与table!中定义的列名完全一致（大小写敏感，取决于数据库配置）。

不依赖顺序的查询方式 #

除了上述的名称匹配模式，还有两种常用方式可以规避顺序依赖：

1. 显式指定查询字段顺序 #

在查询时通过select手动指定与结构体字段顺序一致的列，即使table!的列顺序和结构体不同，也能通过显式对齐避免错误：

fn get_users() -> Vec<User> {
    users::table
        .select((users::id, users::favorite_number, users::name))
        .load::<User>(&mut get_connection())
        .unwrap()
}

这种方式保持编译期类型安全，无额外运行时开销，适合需要精准控制查询字段的场景。

2. 使用QueryableByName trait #

启用Diesel的queryable_by_name feature后，使用QueryableByName trait可以让结构体完全按字段名称匹配查询结果，完全脱离列顺序限制：

首先在Cargo.toml中添加对应feature：

diesel = { version = "2.1", features = ["postgres", "queryable_by_name"] }

然后结构体派生QueryableByName并指定表名：

#[derive(QueryableByName)]
#[diesel(table_name = users)]
struct User {
    id: i32,
    favorite_number: i32,
    name: String,
}

查询时可直接使用load，或配合sql!宏编写原生SQL：

fn get_users() -> Vec<User> {
    sql!("SELECT id, name, favorite_number FROM users")
        .load::<User>(&mut get_connection())
        .unwrap()
}

这种方式适合结构体字段较多或需要灵活调整字段顺序的场景。

内容的提问来源于stack exchange，提问作者kmdreko