⬡ 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进来，经过验证，UserResponse出来，很简单！我们使用处理器为服务创建入口点

• 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特质，因为我们用postgres做了注释。

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

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

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

正如您所看到的，客户端的 C 参数必须实现 DBConnect，它负责连接到数据库，并且其连接必须与 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 文件就会变得更容易阅读

• adapter.rs

  /* ..imports.. */
  
  repository! {
      C => Connection : field_name;
  
      User => UserRepository<Connection>
  }
  
  contract! {
      C => Connection;
  
      RepositoryContract => Repository, RepositoryAccess;
      
      User => UserRepository<Connection>;
  
      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)
      }
  }
  

看起来好多了！这实际上会生成原始文件中所有泛型的代码。您可以在 hextacy::db 模块中了解更多关于宏如何工作的信息。

事务

存储库总是在它们的方法中接受连接的原因是事务。由于业务级服务应该有能力在事情出错时回滚事务，我们必须以某种方式使它们的存储库能够支持事务。

我们通过在存储库中添加一个事务字段来实现这一点，这只是一个围绕 RefCell 的 Option<C> 的结构，其中 C 是连接。我们使用引用细胞来获得对事务的可变访问，而不会通过 &mut self 引用污染我们的API。

现在，这个引用细胞可以保存一个可以用来执行查询的开放连接。Atomic 特性为任何存储库提供了一个接口，用于开始、提交或回滚事务。这是通过检查我们的引用细胞是否包含一个连接来实现的，如果包含，我们就使用那个连接；如果不包含，我们就简单地指示我们的客户端建立一个新连接。更进一步，让我们使用户服务存储库原子化

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>,
}

现在，我们不再简单地建立一个连接并调用 User::get_paginated，而是首先检查是否存在一个开放的连接

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),
      }
  }
}

为了减少匹配连接是否存在时的样板代码，可以使用 atomic! 宏来执行查询。它正好做了上面写的那些事情。

请注意，Repository 已更改为 AcidRepository，而 RepositoryAccess 已更改为 AcidRepositoryAccess。访问特性是相同的，除了原子版本返回一个 AtomicConnection<C> 并要求存储库实现 Atomic，这是 AcidRepository 在幕后实现的

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

pub(super) fn init(cfg: &mut ServiceConfig) {
    let pg = Arc::new(Postgres::new());

    users::setup::routes(pg, cfg);
}

    HttpServer::new(move || {
        App::new()
            .configure(config::init)
            .wrap(Logger::default())
    })
    .bind_openssl(addr, builder)?
    .run()
    .await

cargo install --path xtc

xtc gen route <NAME> -c repository,cache