⬡ Hextacy ⬡

一个仓库，旨在通过提供可扩展的基础设施和CLI工具来快速启动使用 actix_web 的Web服务器开发，同时减少手动编写样板代码，并保持最佳实践。

此仓库使用的项目结构在很大程度上基于 六边形架构，也称为 端口和适配器 架构，它非常灵活且易于测试。您可以在此处阅读有关它的精彩文章 这里 和 这里。

架构

以下是在使用各种hextacy助手时预期的服务器架构，但为了理解为什么它以这种方式构建，您首先需要了解所有助手如何结合在一起以提供高效且灵活的架构。

后端服务器通常，如果不是总是，包含数据存储。 仓库 提供方法，通过这些方法应用程序的 适配器 可以与之交互，以获取对数据库 模型 的访问。

在这个架构中，仓库不包含实现细节。它只是一个接口，适配器利用它进行特定的实现以获取底层模型。因此，仓库方法必须始终接受一个完全通用的连接参数，该参数在适配器实现中被具体化。

当业务级服务需要访问数据库时，它们可以通过具有绑定到所需的任何仓库特质的仓库结构来获取（为了更好地了解这意味着什么，请查看下面的服务器示例或用户示例）。例如，认证服务可能需要访问用户和会话仓库。

在服务的定义中，其存储库必须受到服务所需任何存储库特征的约束。这意味着中间服务存储库也必须接受通用的连接参数。由于服务应该对存储库实现一无所知，这意味着使用该中间存储库来建立数据库连接的客户端也必须是通用的，因为服务无法预先知道它将使用哪个适配器。

可以通过将客户端从业务层移动到适配器层来缓解通用连接，但遗憾的是，我们就会失去执行数据库事务（没有噩梦般的API）的能力。业务层必须保留执行原子查询的能力。

到目前为止，我们有2个通用参数，客户端和连接，我们还有存储库，这些是我们服务的存储库可以利用来获取数据的接口，所以很好！

因为我们现在正在处理完全通用的类型，所以我们有一个完全解耦的架构（耶），但不幸的是，我们现在必须忍受每个中间存储库上Rust的神秘特质限制（啊）。幸运的是，我们可以利用Rust最优秀的特点——宏！

首先，让我们一步步通过查看一个简单的用户端点示例来了解为什么我们需要这些宏。请查看示例存储库中的服务器示例，以了解一切最终是如何设置的。

服务器

首先，我们必须定义我们将使用的数据

• data.rs

  // We expect this in the query params
  // Validify creates a GetUsersPaginatedPayload in the background
  #[derive(Debug, Deserialize)]
  #[validify]
  #[serde(rename_all = "camelCase")]
  pub(super) struct GetUsersPaginated {
    #[validate(range(min = 1, max = 65_535))]
    pub page: Option<u16>,
    #[validate(range(min = 1, max = 65_535))]
    pub per_page: Option<u16>,
  }
  
  // It must derive Serialize and optionally new for convenience (provided by the
  // derive_new crate)
  #[derive(Debug, Serialize, new)]
  pub(super) struct UserResponse {
    users: Vec<User>,
  }
  
  impl Response for UserResponse {}
  

GetUsersPaginated进入，进行验证，UserReponse输出，很简单！我们通过处理器创建服务入口点

• handler.rs

  use super::{contract::ServiceContract, data::GetUsersPaginatedPayload};
  
  pub(super) async fn get_paginated<S: ServiceContract>(
    data: web::Query<GetUsersPaginatedPayload>,
    service: web::Data<S>,
  ) -> Result<impl Responder, Error> {
      let query = GetUsersPaginated::validify(data.0)?;
      info!("Getting users");
      service.get_paginated(query)
  }
  

到目前为止，我们一直在展示一个简单的actix处理器，所以让我们进入好东西。

注意，在我们的处理器中有一个ServiceContract限制。服务通过合约定义其API。合约不过是我们与服务交互的特质（接口）。

• contract.rs

  pub(super) trait ServiceContract {
    fn get_paginated(&self, data: GetUsersPaginated) -> Result<HttpResponse, Error>;
  }
  
  pub(super) trait RepositoryContract {
      fn get_paginated(
          &self,
          page: u16,
          per_page: u16,
          sort: Option<user::SortOptions>,
      ) -> Result<Vec<User>, Error>;
  }
  

这些合约定义了我们从服务中获得的行为及其将使用的基础设施。服务合约由服务结构实现。

• service.rs

  pub(super) struct UserService<R>
  where
      R: RepositoryContract,
  {
      pub repository: R,
  }
  
  impl<R> ServiceContract for UserService<R>
  where
      R: RepositoryContract,
  {
      fn get_paginated(&self, data: GetUsersPaginated) -> Result<HttpResponse, Error> {
          let users = self.repository.get_paginated(
              data.page.unwrap_or(1_u16),
              data.per_page.unwrap_or(25),
              data.sort_by,
          )?;
  
          Ok(UserResponse::new(users)
              .to_response(StatusCode::OK)
              .finish())
      }
  }
  

服务有一个字段，必须实现合约。这个合约充当抽象层，使得我们现在不需要关心repository字段中有什么，只要它实现了RepositoryContract。这有助于在即将到来的存储库中设置通用限制，并使服务测试变得轻而易举！

现在我们必须定义我们的存储库，这时我们进入了Rust特质限制的神秘领域

• adapter.rs

  use hextacy_derive::Repository;
  use hextacy::clients::db::{Client, DBConnect};
  use std::{marker::PhantomData, sync::Arc};
  
  #[derive(Debug, Clone, Repository)]
  #[postgres(Conn)]
  pub struct Repository<C, Conn, User>
  where
      C: DBConnect<Connection = Conn>,
      User: UserRepository<Conn>,
  {
      postgres: Client<C, Conn>,
      user: PhantomData<User>,
  }
  
  // This one's for convenience
  impl<C, Conn, User> Repository<C, Conn, User>
  where
      C: DBConnect<Connection = Conn>,
      User: UserRepository<Conn>
  {
      pub fn new(client: Arc<A>) -> Self {
          Self {
              client: Client::new(client),
              user: PhantomData
          }
      }
  }
  
  impl<C, Conn, User> RepositoryContract for Repository<C, Conn, User> 
  where
      Self: RepositoryAccess<Conn>,
      C: DBConnect<Connection = Conn>,
      User: UserRepository<Conn>
  {
    fn get_paginated(
        &self,
        page: u16,
        per_page: u16,
        sort: Option<user::SortOptions>,
    ) -> Result<Vec<user::User>, Error> {
        let mut conn = self.connect()?;
        User::get_paginated(&mut conn, page, per_page, sort).map_err(Error::new)
    }
  }
  

仅仅为了从数据库中获取用户就做了这么多工作。

Repository derive使用PgPoolConnection作为其连接类型实现RepositoryAccess特质，因为我们用PostgreSQL进行了注释。

RepositoryAccess是一个简单的特质，它是关于连接的通用类型，并为其实现者提供了一个connect()方法，用于建立到数据库的连接。在Repository derive中，这个通用连接被具体化为PgPoolConnection，这基本上意味着我们可以使用任何可以建立这种连接的客户端。Postgres客户端可以做到这一点（它只是连接池的包装器）。

属性 #[postgres(Conn)] 通知 derive 宏在实现中替换哪个通用连接参数，并且必须与结构体中的通用参数匹配。 RepositoryAccess 也可以手动实现。

DBConnect 是客户端用于建立实际连接的 trait。所有具体的客户端都以它们自己的方式实现它。它还由 Client 结构体实现。一个 Client 是一个具体客户端的包装器，简单地将其 connect() 调用委托给它。

如您所见，客户端的 C 参数必须实现 DBConnect，该 trait 负责连接到数据库，其连接必须与 DBConnect 上的连接相同。这处理了我们如何连接到数据库的方式。

User 绑定只是将服务使用的存储库绑定到存储库，在这种情况下是 UserRepository。由于存储库方法必须接受一个连接（为了保持事务），它们不接收 &self。这是可以的，但现在编译器会抱怨我们有未使用的字段，因为我们实际上没有使用它们。如果我们删除这些字段，编译器会抱怨我们有未使用的特质约束，所以我们使用幻数来让编译器认为结构体拥有这些数据。

到目前为止，我们没有将任何实现细节与服务耦合。derive 宏为 postgres 客户端生成代码，但它只是在 RepositoryAccess 实现中将通用连接约束替换为具体约束。之所以称为 postgres，是因为 derive 宏在特定字段上操作，在手动实现的情况下，这可以命名为任何名称。

所以，基本上，服务只有对一些通用客户端、连接和存储库的调用。

这一事实是该架构的核心，也是它如此强大的原因。这不仅使得测试变得轻而易举，而且还允许我们随意更改适配器，而无需更改业务逻辑。它们是完全解耦的。

最后，我们在设置中具体化所有内容

• setup.rs

  pub(crate) fn routes(pg: Arc<Postgres>, rd: Arc<Redis>, cfg: &mut web::ServiceConfig) {
    let service = UserService {
        repository: Repository::<Postgres, PgPoolConnection, PgUserAdapter>::new(pg.clone()),
    };
    let auth_guard = interceptor::AuthGuard::new(pg, rd, Role::User);
  
    cfg.app_data(Data::new(service));
  
    // Show all
    cfg.service(
        web::resource("/users")
            .route(web::get().to(handler::get_paginated::<
                UserService<Repository<Postgres, PgPoolConnection, PgUserAdapter>>,
            >))
            .wrap(auth_guard),
    );
  }
  

我必须承认，特质约束看起来有点丑，但鉴于这是我们唯一具体化类型的地方，我们不必担心在适配器中做出更改时，服务的其余部分会损坏。

为了减少处理这么多泛型的不愉快，存在宏来帮助这个过程。如果我们使用 repository! 和 contract! 宏，我们的 adapter.rs 文件将更容易阅读

use hextacy_derive::Repository;
use hextacy::db::{AtomicConnection, Transaction};
use hextacy::clients::db::{Client, DBConnect};
use std::{marker::PhantomData, sync::Arc};

#[derive(Debug, Clone, AcidRepository)]
#[postgres(Conn)]
pub struct Repository<C, Conn, User>
where
    C: DBConnect<Connection = Conn>,
    User: UserRepository<Conn>,
{
    pub postgres: Client<C, Conn>,
    // Type provided for convenience which is equivalent to RefCell<Option<Conn>>
    pub pg_tx: Transaction<Conn>,
    user: PhantomData<User>,
}

impl<C, Conn, User> RepositoryContract for Repository<C, Conn, User> 
where
    Self: AcidRepositoryAccess<Conn>,
    C: DBConnect<Connection = Conn>,
    User: UserRepository<Conn>
{
  fn get_paginated(
      &self,
      page: u16,
      per_page: u16,
      sort: Option<user::SortOptions>,
  ) -> Result<Vec<user::User>, Error> {
      let mut conn = self.connect()?;
      // Use atomic! to reduce this boilerplate
      match conn {
        hextacy::db::AtomicConnection::New(mut conn) => User::get_paginated(&mut conn, page, per_page, sort).map_err(Error::new),
        hextacy::db::AtomicConnection::Existing(mut conn) => User::get_paginated(conn.borrow_mut().as_mut().unwrap(), page, per_page, sort).map_err(Error::new),
      }
  }
}

use hextacy::db::{Atomic, DatabaseError, TransactionError};
use diesel::connection::AnsiTransactionManager;

impl</* ..bounds.. */> Atomic for Repository< /* ..bounds.. */, PgPoolConnection>
where /* ..bounds.. */ 
{
      fn start_transaction(&self) -> Result<(), DatabaseError> {
          let mut tx = self.transaction.borrow_mut();
          match *tx {
              Some(_) => Err(DatabaseError::Transaction(TransactionError::InProgress)),
              None => {
                  let mut conn = self.client.connect()?;
                  AnsiTransactionManager::begin_transaction(&mut *conn)?;
                  *tx = Some(conn);
                  Ok(())
              }
          }
      }

      fn rollback_transaction(&self) -> Result<(), DatabaseError> {
          let mut tx = self.transaction.borrow_mut();
          match tx.take() {
              Some(ref mut conn) => AnsiTransactionManager::rollback_transaction(&mut **conn)
                  .map_err(DatabaseError::from),
              None => Err(DatabaseError::Transaction(TransactionError::NonExisting).into()),
          }
      }

      fn commit_transaction(&self) -> Result<(), DatabaseError> {
          let mut tx = self.transaction.borrow_mut();
          match tx.take() {
              Some(ref mut conn) => {
                  AnsiTransactionManager::commit_transaction(&mut **conn)
                      .map_err(DatabaseError::from)
              }
              None => Err(DatabaseError::Transaction(TransactionError::NonExisting).into()),
          }
      }
  }

pub trait UserRepository<C> {
    fn get_paginated(
        conn: &mut C,
        page: u16,
        per_page: u16,
        sort_by: Option<SortOptions>,
    ) -> Result<Vec<User>, AdapterError>;
}

  - full - Enables all the feature below

  - db - Enables mongo, diesel and redis
  - ws - Enable the WS session adapter and message broker

  - diesel - Enables the diesel postgres client and derive macros
  - mongo - Enables the mongodb client and derive macros
  - redis - Enables the redis client and cache access trait
  - email - Enables the SMTP client and lettre

cargo install --path xtc

xtc gen route <NAME> -c repository,cache