A package based on Golang and MongoDB for quickly building HTTP RESTful services with JSON.
- go 1.13+
- mongodb v3.4.x v3.6.x
- elasticsearch v6.8.x v7.x.x (if enable searching)
Use go get.
go get github.com/jimdn/restful/v2
Then import the package into your own code.
import "github.com/jimdn/restful/v2"
- Define the structure of the data resource (including json and bson tags), then you can implement the CURD service of HTTP+JSON. The protocol is as follows:
HTTP Method | Path | URL Params | HTTP Body | Explain |
---|---|---|---|---|
POST | /{biz} | - | data to be inserted | insert data |
PUT | /{biz}/{id} | - | data to be upserted | insert or update(overwrite) data by id |
PATCH | /{biz}/{id} | seq | data to be updated | update data by id |
DELETE | /{biz}/{id} | - | - | delete data by id |
GET | /{biz}/{id} | - | - | get data by id |
GET | /{biz} | page size filter range in nin all search order select |
- | get list of data: page=1 size=10 filter={"star":5, "city":"shenzhen"} range={"age":{"gt":20, "lt":40}} in={"color":["blue", "red"]} nin={"color":["blue", "red"]} all={"color":["blue", "red"]} search=hello order=["+age", "-time"] select=["id", "name", "age"] |
-
When defining a data resource structure, the supported data types include:
common types: bool int32 uint32 int64 uint64 float32 float64 string struct array types: []bool []int32 []uint32 []int64 []uint64 []float32 []float64 []string []struct map types: map[string]bool map[string]int32 map[string]uint32 map[string]int64 map[string]uint64 map[string]float32 map[string]float64 map[string]string map[string]struct
-
Support field level
CreateOnly
orReadOnly
:- CreateOnly: only allows creation, does not allow subsequent modification of the field
- ReadOnly: only allows reading, does not allow creation and modification, is suitable for importing data from other systems to the database, and then providing data reading services.
-
With the field check function, the incoming data field type is wrong or does not exist, it will return a failure and prompt specific error information.
-
Support custom data ID or automatically create ID (UUIDv4), pay attention to the writing of tags:
type Foo struct { Id *string `json:"id,omitempty" bson:"_id,omitempty"` ... }
-
Support tracking data birth time and modify time, two additional fields required:
- btime: birth time, record the timestamp when data created
- mtime: modify time, record the timestamp the last modification of data
-
Support anti-concurrent writing, the
seq
field required:- seq: will be updated each time the data is modified, the update (PATCH) request needs to bring the data original seq to prevent concurrent writing from causing data confusion.
-
Support custom database name and table name, with URL params:
- db: database name, default is restful
- table: table name, default is {Biz}
e.g.: /{Biz}?db=dbName&table=tableName
See examples. We take the Student
of simple.go as an example:
Request:
POST /student HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226
{
"id": "student-id-001",
"name": "jimmydeng",
...
}
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 91
{
"code": 0,
"msg": "post ok",
"data": {
"id": "student-id-001"
}
}
Request:
PUT /student/student-id-001 HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226
{
"id": "student-id-001",
"name": "jimmydeng",
...
}
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 90
{
"code": 0,
"msg": "put ok",
"data": {
"id": "student-id-001"
}
}
Request:
PATCH /student/student-id-001?seq=1 HTTP/1.1
Content-Type: application/json; charset=utf-8
Content-Length: 226
{
"id": "student-id-001",
"name": "jimmydeng02",
...
}
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 30
{
"code": 0,
"msg": "patch ok",
"data": {
"id": "student-id-001"
}
}
Request:
DELETE /student/student-id-001 HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 30
{
"code": 0,
"msg": "delete ok",
"data": {
"id": "student-id-001"
}
}
Request:
GET /student/student-id-001 HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 537
{
"code": 0,
"msg": "get ok",
"data": {
"id": "student-id-001"
"name": "jimmydeng",
...
}
}
Request:
GET /student?page=1&size=10 HTTP/1.1
Response:
HTTP/1.1 200 OK
Date: Mon, 22 Apr 2019 06:46:23 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 797
{
"code": 0,
"msg": "get page ok",
"data": {
"total": 238,
"hits": [
{
"id": "student-id-001",
"name": "jimmydeng",
...
},
{
"id": "student-id-002",
"name": "tonywho",
...
}
...
]
}
}