rabbithole-rs

兔子洞径一直向前延伸，像隧道一样，然后突然向下倾斜，如此之快，爱丽丝甚至没有时间思考如何阻止自己，就发现自己掉进了一个看起来非常深的井。

-- 《爱丽丝梦游仙境》，路易斯·卡罗尔著

简介

rabbithole-rs是一个类型安全的、用户友好的JSON:API类型系统，包含一个易于使用的宏系统，帮助您建模数据。

大量受到jsonapi-rust的启发，事实上，测试中的所有示例数据都来自这个crate。干得好，michiel!

那么什么是JSON:API呢？

如果您曾经与团队就JSON响应的格式进行过争论，JSON:API可以成为您的防车棚工具。

通过遵循共享约定，您可以提高生产力，利用通用工具，并专注于最重要的：您的应用程序。

当您设计RESTful API时，最令人烦恼的问题是如何设计数据结构，特别是如何设计错误系统。所以JSON:API为像您这样的人设计了一个规范，以指定一些规则来帮助您处理设计问题，解放您的时间！

也许规范很长很无聊，就像读教科书一样，但请相信我，您将从中学到很多东西，就像教科书一样。 :)

那么为什么还需要另一个JSON:API crate呢？

RSQL支持需求

这个crate的主要原因是，我需要支持RSQL/FIQL，因为我认为它是一个定义良好的复杂查询系统。JSON:API没有提供官方的查询/过滤器解决方案，但我认为RSQL/FIQL足以处理我的项目。

有关RSQL/FIQL的更多信息，请参阅

• rsql-rs，我的项目，请查看并给我一个Star，THX！
• rsql-parser（可能是最好的RSQL解析实现）
• FIQL规范

类型安全的系统

作为一名Scala程序员，我认为一个设计良好的类型系统可以避免很多问题。我想知道Rust的ADT系统是否可以处理这类复杂问题。实际上，它可以很好地处理。

用户友好的宏和建模

作为一名Java开发者，我非常喜欢注解系统。幸运的是，Rust使用proc_macro系统为用户提供“最精确相同的”体验。

例如，而不是

#[derive(Debug, PartialEq, Serialize, Deserialize)]
struct Dog {
    id: String,
    name: String,
    age: i32,
    main_flea: Flea,
    fleas: Vec<Flea>,
}
jsonapi_model!(Dog; "dog"; has one main_flea; has many fleas);

我可以这样建模我的数据结构

#[derive(rbh_derive::EntityDecorator, Serialize, Deserialize, Clone)]
#[entity(type = "dogs")]
pub struct Dog<'a> {
    #[entity(id)]
    pub id: String,
    pub name: String,
    #[entity(to_many)]
    pub fleas: Vec<Flea>,
    #[entity(to_many)]
    pub friends: Vec<Dog<'a>>,
    #[entity(to_one)]
    #[serde(bound(deserialize = "Box<Human<'a>>: Deserialize<'de>"))]
    pub master: Box<Human<'a>>,
    #[entity(to_one)]
    pub best_one: Option<Box<Dog<'a>>>,
}

对我来说，第二种方式更美观。

功能

• 基本的JSON:API模型系统

• 基本的宏系统

• 基本的测试

• 查询/过滤API

  • 查询/过滤模型
  • （部分完成）现在可以实现自动查询/过滤

• 更严格的类型检查和错误提示

• 高性能的JSON:API服务器

  • actix后端
  • （可能）Hyper后端

一些问题

使用关系路径进行查询不工作

查看详细问题。

使用分页查询时缺少额外的meta和links字段

在规范中，当使用page查询时，

• meta对象应添加一个totalPage字段
• links对象应添加prev、next、first和last链接，但是rabbithole不能自动处理，用户应通过在Fetching::vec_to_document中手动实现来添加这些字段。

未来工作

宏系统中的类型检查和错误提示

rabbithole-rs有很多类型限制。例如

• [#to_one]装饰器只能用于类型为

  • rabbithole::entity::Entity
  • 或rabbithole::entity::Entity的包装类的字段
    • Option<T>
    • Box<T>
    • &T
    • 另一个包装类内部的包装类，如Option<Box<T>>

• #[to_many]装饰器只能用于具有以下属性的字段

  • 一个迭代器
  • 迭代器的内部类型应满足上述限制
  • 没有嵌套列表（讨论中）

现在由于Rust缺少反射，宏现在不能检查任何类型错误，因此可能需要一些解决方案。

高性能服务器

由于JSON:API的API接口复杂，我认为自己编写所有遵循规范的API接口是多余且乏味的工作，所以我会为你做这些乏味的事情！

我对这个项目的最终目标

这个项目的最终目标就像crnk或elide一样，可以根据模型（可能是DAO）的定义自动生成大量的API。在这里，我想仅仅展示项目最终会是什么样子。

定义模型

第一步是定义一些API友好的模型。

// This is the derive crate which you can use to generate JSON:API specific traits
extern crate rabbithole_derive as rbh_derive;

#[derive(rbh_derive::EntityDecorator, Serialize, Deserialize, Clone)]
#[entity(type = "people")]
pub struct Human {
    #[entity(id)]
    pub id_code: Uuid,
    pub name: String,
    #[entity(to_many)]
    pub dogs: Vec<Dog>,
}

#[derive(rbh_derive::EntityDecorator, Serialize, Deserialize, Clone)]
#[entity(type = "dogs")]
pub struct Dog {
    #[entity(id)]
    pub id: Uuid,
    pub name: String,
}

编写你自己的DAO

rabbithole 没有绑定到任何特定的数据库，这意味着您必须自己编写 DAO。

有关详细信息，请参阅 rabbithole-endpoint-actix/examples/mock_gen.rs。

Fetching 特性是什么

Fetching 特性是 JSON:API 中“获取数据”部分的映射，它定义了几个操作

• 获取资源
  • 单个资源：GET /articles/1
  • 多个资源：GET /articles
  • 相关资源：GET /articles/1/author，可以是单个或多个
• 获取关系
  • 关系：GET /articles/1/relationships/comments
• 使用查询参数获取
  • 相关资源的包含（include 部分）
  • 稀疏字段集（fields[TYPE] 部分）
  • 排序（sort 部分）
  • 分页（page 部分）

这些都是我们在“获取数据”部分需要了解的内容。因此，这些操作被抽象为 Fenching 特性。

vec_to_document 部分是什么？

如果您想将 Vec<SingleEntity> 转换为 Document，它将执行许多操作，例如 排除未包含的资源、保留稀疏字段 等。当然，我可以在后台帮助您（使用 Entity::to_document_automatically）。但是，为什么不仅要提取所有字段并稍后丢弃它们，而不直接将它们留在数据库中呢？所以这就是关键所在。如果您不想编写将 Vec<SingleEntity> 转换为文档的代码，只需使用 Entity::to_document_automatically，或者，您可以直接从数据库组装 Document。