jsonapi - jsonapi.org style payload serializer and deseriali

项目说明

jsonapi

![Build Status]()
![Go Report Card]()
![GoDoc]()
![No Maintenance Intended]()

A serializer/deserializer for JSON payloads that comply to the
JSON API - jsonapi.org spec in go.

Installation

Or, see Alternati.

Background

You are working in your Go web application and you have a struct that is
organized similarly to your 数据库 schema. You need to send and
receive json payloads that adhere to the JSON API spec. Once you realize that
your json needed to take on this special form, you go down the path of
creating more structs to be able to serialize and deserialize JSON API
payloads. Then there are more models required with this additional
structure. Ugh! With JSON API, you can keep your model structs as is and
use StructTags to indicate
to JSON API how you want your response built or your request
deserialized. What about your relationships? JSON API supports
relationships out of the box and will even put them in your response
into an included side-loaded slice--that contains associated records.

Introduction

JSON API uses StructField
tags to annotate the structs fields that you already have and use in
your app and then reads and writes JSON API
output based on the instructions you give the library in your JSON API
tags. Let's take an example. In your app, you most likely ha
that look similar to these:

These structs may or may not resemble the layout of your 数据库. But
these are the ones that you want to use right? You wouldn't want to use
structs like those that JSON API sends because it is difficult to get at
all of your data easily.

Example App

examples/app.go

This program demonstrates the implementation of a create, a show,
and a list http.Handler. It
outputs some example requests and responses as well as serialized
examples of the 源码/target structs to json. That is to say, I show
you that the library has successfully taken your JSON API request and
turned it into your struct types.

To run,

* Make sure you have Go installed
* Create the following directories or similar: ~/go
* Set GOPATH to PWD in your shell session, export GOPATH=$PWD
* go get github.com/google/jsonapi. (Append -u after get if you
are updating.)
* cd $GOPATH/src/github.com/google/jsonapi/examples
* go build && ./examples

jsonapi Tag Reference

Example

The jsonapi StructTags
tells this library how to marshal and unmarshal your structs into
JSON API payloads and your JSON API payloads to structs, respectively.
Then Use JSON API's Marshal and Unmarshal methods to construct and read
your responses and replies. Here's an example of the structs above
using JSON API tags:

Permitted Tag

#### primary

This indicates this is the primary key field for this struct type.
Tag value arguments are comma separated. The first argument must be,
primary, and the second must be the name that should appear in the
type\* field for all data objects that represent this type of model.

\* According the JSON API spec, the plural record
types are shown in the examples, but not required.

#### attr

These fields' will end up in the attributeshash for a record.
The first argument must be, attr, and the second should be the name
for the key to display in the attributes hash for that record. The optional
third argument is omitempty - if it is present the field will not be present
in the "attributes" if the field's value is equi to the field types
empty value (ie if the count field is of type int, omitempty will omit the
field when count has a value of 0). Lastly, the spec indicates that
attributes key names should be dasherized for multiple word field names.

#### relation

Relations are struct fields that represent a one-to-one or one-to-many
relationship with other structs. JSON API will traverse the graph of
relationships and marshal or unmarshal records. The first argument must
be, relation, and the second should be the name of the relationship,
used as the key in the relationships hash for the record. The optional
third argument is omitempty - if present will prevent non existent to-one and
to-many from being serialized.

Methods Reference

**All Marshal and Unmarshal methods expect pointers to struct
instance or slices of the same contained with the interface{}s**

Now you have your structs prepared to be serialized or materialized, What
about the rest?

Create Record Example

You can Unmarshal a JSON API payload using
jsonapi.UnmarshalPayload.
It reads from an io.Reader
containing a JSON API payload for one record (but can ha
records). Then, it materializes a struct that you created and passed in
(using new or &). Again, the method supports single records only, at
the top level, in request payloads at the moment. Bulk creates and
updates are not supported yet.

After saving your record, you can use,
MarshalOnePayload,
to write the JSON API response to an
io.Writer.

#### UnmarshalPayload

Visit godoc

#### MarshalPayload

Visit godoc

Writes a JSON API response, with related records sideloaded, into an
included array. This method encodes a response for either a single record or
many records.

##### Handler Example Code

Create Records Example

#### UnmarshalManyPayload

Visit godoc

Takes an io.Reader and a reflect.Type representing the uniform type
contained within the "data" JSON API member.

##### Handler Example Code

Links

If you need to include link objects along with response data, implement the Linkable interface for document-links, and RelationshipLinkable for relationship links:

Meta

If you need to include meta objects along with response data, implement the Metable interface for document-meta, and RelationshipMetable for relationship meta:

Custom types

Custom types are supported for primiti, only, as attributes. Examples,

Types like following are not supported, but may be in the future:

Errors

This package also implements support for JSON API compatible errors payloads using the following types.

#### MarshalErrors

Writes a JSON API response using the given []error.

#### ErrorsPayload

ErrorsPayload is a serializer struct for representing a valid JSON API errors payload.

#### ErrorObject

ErrorObject is an Error implementation as well as an implementation of the JSON API error object.

The main idea behind this struct is that you can use it directly in your 代码 as an error type and pass it directly to MarshalErrors to get a valid JSON API errors payload.

##### Errors Example Code

Testing

MarshalOnePayloadEmbedded

Visit godoc

This method is not strictly meant to for use in implementation 代码,
although feel free. It was mainly created for use in tests; in most cases,
your request payloads for create will be embedded rather than sideloaded
for related records. This method will serialize a single struct pointer
into an embedded json response. In other words, there will be no,
included, array in the json; all relationships will be serialized
inline with the data.

However, in tests, you may want to construct payloads to post to create
methods that are embedded to most closely model the payloads that will
be produced by the 客户端. This method aims to enable that.

Example

Alternati

I use git subtrees to manage dependencies rather than go get so that
the src is committed to my repo.

To update,

This assumes that I have my repo structured with a src dir containing
a collection of packages and GOPATH is set to the root
folder--containing src.

Contributing

Fork, Change, Pull Request *with tests*.

项目信息

开发语言：Go

Star 数：1411

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕jsonapi.org style payload serializer and deserializer展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。