ja_serializer, 在tcm中,JSONAPI.org 序列化

分享于 

14分钟阅读

GitHub

  繁體 雙語
JSONAPI.org Serialization in Elixir.
  • 源代码名称:ja_serializer
  • 源代码网址:http://www.github.com/vt-elixir/ja_serializer
  • ja_serializer源代码文档
  • ja_serializer源代码下载
  • Git URL:
    git://www.github.com/vt-elixir/ja_serializer.git
    Git Clone代码到本地:
    git clone http://www.github.com/vt-elixir/ja_serializer
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/vt-elixir/ja_serializer
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    JaSerializer

    Build StatusHex VersionDeps StatusInline docs

    适用于库的Elixir数据结构的jsonapi.org 格式,如毒药。

    问题/帮助

    请打开一个问题或者消息/消息/提及 @alanpeabody 在 Elixir松弛。

    用法

    有关完整的序列化和使用细节,请参阅hexdoc上的文档

    安装

    将JaSerializer添加到应用程序

    mix.deps

    defpdepsdo [#.. . {:ja_serializer, "~> x.x.x"}#.. . ]end

    序列化程序行为和 DSL

    defmoduleMyApp.ArticleSerializerdouseJaSerializer location "/articles/:id" attributes [:title, :tags, :body, :excerpt]
     has_one :author,
     serializer:PersonSerializer,
     include:true,
     field::authored_by has_many :comments,
     links: [
     related:"/articles/:id/comments",
     self:"/articles/:id/relationships/comments" ]
     defcomments(article, _conn) doComment.for_article(article)
     enddefexcerpt(article, _conn) do [first | _ ] =String.split(article.body, ".")
     first
     endend

    属性

    属性被定义为序列化程序模块中的列表。 默认情况下,序列化程序将使用给定的Atom 作为密钥。 你还可以通过定义 <attribute_name>/2 方法来指定属性检索的自定义方法。 方法将传递结构和连接。

    关系

    有效关系为:has_onehas_many。 将 has_one 用于 belongs_to 类型的关系。 对于每个关系,你都可以定义名称和各种选项。 属性一样,序列化程序将使用给定的Atom 查找关系,除非指定自定义检索方法或者提供 field 选项。

    关系选项
    • 序列化程序- 序列化这里资源时要使用的序列化程序
    • 将- boolean - true 包含到始终加载这里关系
    • 字段- 用于关系检索的自定义字段
    • 链接- relationships 哈希中使用的自定义链接

    序列化程序的直接使用

    MyApp.ArticleSerializer|>JaSerializer.format(struct, conn)|>Poison.encode!

    格式选项

    format/4 方法可以接受可以定制序列化负载的选项。

    包括

    通过指定 include 选项,序列化程序将只侧载指定的。 这里选项应该是逗号分隔的关系列表。 每一个关系都应该是一个分开的路径。

    示例:include:"author,comments.author"

    这个字符串的格式应该与由 json api规范指定的字符串完全匹配。

    注意:如果指定 include 选项,所有"默认值"都将被忽略,并且每个规范中只包含指定的关系。

    字段

    fields 选项满足规范的稀疏字段集部分。 这里选项应该是资源类型的映射,它的值是一个逗号分隔的字段列表,其中包含。

    例如: fields: %{"articles" =>"title,body","comments" =>"body"}

    如果你使用 Plug,你应该能够调用 fetch_query_params(conn) 并将 conn.query_params["fields"]的结果作为这里选项传递。

    使用

    在视图( 或者在Web模块中) 中简单地 use JaSerializer.PhoenixView,并在上面定义。

    为你定义了 render("index.json-api", data)render("show.json-api", data)。 你可以从控制器中直接调用 render。

    通过在调用render函数时指定 include,可以重写ArticleView中的include: false

    defmodulePhoenixExample.ArticlesControllerdousePhoenixExample.Web, :controllerdefindex(conn, _params) do render conn, "index.json-api", data:Repo.all(Article)
     enddefshow(conn, %{"id"=> id}) do article =Repo.get(Article, id) |>Repo.preload([:comments])
     render conn, "show.json-api", data: article,
     opts: [include:"comments"]
     enddefcreate(conn, %{"data"=> data}) do attrs =JaSerializer.Params.to_attributes(data)
     changeset =Article.changeset(%Article{}, attrs)
     caseRepo.insert(changeset) do {:ok, article} -> conn
     |> put_status(201)
     |> render("show.json-api", data: article)
     {:error, changeset} -> conn
     |> put_status(422)
     |> render(:errors, data: changeset)
     endendenddefmodulePhoenixExample.ArticlesViewdousePhoenixExample.Web, :viewuseJaSerializer.PhoenixView# Or use in web/web.ex attributes [:title]
     has_many :comments,
     serializer:PhoenixExample.CommentsView,
     include:false,
     identifiers::when_included#has_many, etc.end

    配置

    要使用 Phoenix accepts 插头,必须配置插头来处理"应用程序/vnd。api+json"mime类型,并使用Poison将 json-api序列化为。

    根据你的插件版本,将以下内容添加到 config.exs:

    插入 ~>"1.2.0""

    config :phoenix, :format_encoders,
     "json-api": Poisonconfig :mime, :types, %{
     "application/vnd.api+json"=> ["json-api"]
    }

    然后编译 mime: ( 每个: https://hexdocs.pm/mime/MIME.html )

    mix deps.clean mime --build
    mix deps.get

    插头 <"1.2.0"

    config :phoenix, :format_encoders,
     "json-api": Poisonconfig :plug, :mimes, %{
     "application/vnd.api+json"=> ["json-api"]
    }

    然后编译插头:( 每: https://hexdocs.pm/plug/1.1.3/Plug.MIME.html )

    mix deps.clean plug --build
    mix deps.get

    然后将 json api添加到你的plug管道。

    pipeline :apido plug :accepts, ["json-api"]end

    严格 Content-Type/接受强制,并自动添加适当的Content-Type 到响应中,添加 JaSerializer.ContentTypeNegotiation 插头。

    将属性规范化为下划线包括 JaSerializer.Deserializer 插头。

    pipeline :apido plug :accepts, ["json-api"]
     plug JaSerializer.ContentTypeNegotiation plug JaSerializer.Deserializerend

    在使用 404.json-api API的情况下,你必须将 json-api 添加到你的现有配置中,例如:

    config :phoenix, PhoenixExample.Endpoint,
     render_errors: [view:PhoenixExample.ErrorView, accepts:~w(html json json-api)]

    测试控制器

    setup 中设置正确的标题,并将参数传递给,和post请求,应当将它们作为二进制文件传递。 这是因为对于映射和列表参数,Content-Type 将自动更改为多部分。

    defmoduleSample.SomeControllerTestdouseSample.ConnCase setup %{conn: conn} do conn = conn
     |> put_req_header("accept", "application/vnd.api+json")
     |> put_req_header("content-type", "application/vnd.api+json")
     {:ok, conn: conn}
     end test "create action", %{conn: conn} do params =Poison.encode!(%{data: %{attributes:@valid_attrs}})
     conn = post conn, "/some_resource", params
     ...
     end...end

    JSON API生成器

    使用我们内置的发电机快速启动和运行。 它使用与 phoenix json生成器相同的格式。

    mix ja_serializer.gen.phoenix_api Checkbox checkboxes description:string checked:boolean list_id:references:lists

    想调整我们的模板? 在'priv/templates/ja_serializer.gen.phoenix_api/'下插入你自己的,我们将用你的。

    分页

    JaSerializer提供基于页面的分页集成与 Scrivener 或者自定义分页,通过通过你的。

    自定义

    JaSerializer允许通过 page 选项进行自定义分页。 page 选项期望接收带有 firstnextprevlast URL值的Map

    例如:

    page = %{
     first:"http://example.com/api/v1/posts?page[cursor]=1&page[per]=20",
     prev:nilnext:"http://example.com/api/v1/posts?page[cursor]=20&page[per]=20",
     last:"http://example.com/api/v1/posts?page[cursor]=60&page[per]=20"}# Direct callJaSerializer.format(MySerializer, collection, conn, page: page)# In Phoenix Controllerrender conn, data: collection, opts: [page: page]
    生成器

    你可以生成分页链接,方法是 JaSerializer.Builder.PaginationLinks.build/2

    只需传递以下内容:

    links =JaSerializer.Builder.PaginationLinks.build(%{
     number:2,
     size:10,
     total:20})

    请参见 JaSerializer.Builder.PaginationLinks 关于如何自定义。

    Scrivener集成

    如果使用Scrivener进行分页,只需将 paginate/2的结果传递给序列化程序。

    page =MyRepo.paginate(MyModel, params.page)# Direct callJaSerializer.format(MySerializer, page, conn, [])# In Phoenix controllerrender conn, data: page

    当与Scrivener集成时,生成的url将基于 Plug.Conn的路径。 这可以通过传入 page[:base_url] 选项来覆盖。

    render conn, data: page, opts: [page: [base_url:"http://example.com/foos"]]

    你还可以配置 ja_serializer 以使用所有链接的全局缺省URL库。

    config :ja_serializer,
     scrivener_base_url:"http://example.com:4000/v1/"

    :的url将使用推荐的page 查询参数查询参数。

    示例网址: http://example.com:4000/v1/posts?page[page]=2&page[page-size]=50

    元数据

    JaSerializer允许通过 meta 选项添加顶级元信息。 meta 选项期望接收包含将在顶级元键下呈现的数据的Map

    meta_data = %{
     "key"=>"value"}# Direct callJaSerializer.format(MySerializer, data, conn, meta: meta_data)# In Phoenix controllerrender conn, data: data, opts: [meta: meta_data]

    文档级自定义项

    ( 用于属性。关系和查询参数)的密钥格式

    默认情况下,键按 jsonapi.org 建议是 dash-erized,但键可以通过配置来定制。

    config.exs file: 中

    config :ja_serializer,
     key_format::underscored

    还可以将自定义函数传递给序列化,也可以传递第二个用于反序列化的自定义函数。 两个都接受一个二进制参数:

    defmoduleMyStringModuledodefcamelize(key), do: key #...defunderscore(key), do: key #...endconfig :ja_serializer,
     key_format: {:custom, MyStringModule, :camelize, :underscore}

    如果已经编译了代码,请确保运行 mix deps.clean ja_serializer && mix deps.get

    自定义属性值格式化程序

    序列化属性值比字符串。数字。原子或者这些事情的列表更复杂时,建议实现一个自定义格式化程序。

    若要实现自定义格式化程序,请执行下列操作:

    defimplJaSerializer.Formatter, for: [MyStruct] dodefformat(struct), do: structend

    默认情况下 Pluralizing所有类型

    你可以选择在默认情况下为pluralizing选择所有类型:

    config :ja_serializer,
     pluralize_types:true

    免费图书馆

    许可证

    JaSerializer源代码是在 Apache 2许可证下发布的。 查看许可证文件以获得更多信息。


    相关文章