shu

shu is a library for http client request for restful api only with declaration.

The client file could be generated by some tool from OpenAPI Specification api doc.

This will help developer define there apis in server side.

usage:

TD,LR: you could copy file tmpl/definition.go.template to quickly define your apis.

using shugen to generate api file

go get github.com/damonchen/shugen

package client

import "github.com/damonchen/shu"

//go:generate shugen generate.go -o client.go

var (
	// must define var name to  bundle
	// using bundle.SetOption(client.WithAuth(auth), client.WithConfig(config)) to set
	// the auth and config outside
	bundle = shu.NewBundle()
)

type UserLogin struct {
	Name     string `param:"name;pos:query"`
	Password string `param:"password"`
}

type UserLoginResp struct {
	Status string `json:"status"`
}

func init() {
	bundle.Client(shu.Client{
		Name: "auth",        // client name, must unique in client
		APIs: []*shu.API{
			{
				Name:     "login",      // client function name, must unique in client
				Path:     "/api/v1/login",      // really api path, support ${var}, which will be replaced by param definition
				Method:   shu.POST,     // api method will be used
				Params:   UserLogin{},      // request param, should given struct instance
				Response: UserLoginResp{},  // response body, should given struct instance
			},
		},
	},
	)
	bundle.Init()
}

func GetBundle() *shu.Bundle {
	return bundle
}

when run go generate, it will generate the following code:

package client

type AuthClient struct {
}

func (c AuthClient) Login(userLogin UserLogin) (*UserLoginResp, error) {
	resp, err := bundle.Get("auth").Call("login", userLogin)
	if err != nil {
		return nil, err
	}
	return resp.(*UserLoginResp), nil
}

func GetAuthClient() AuthClient {
	return AuthClient{}
}

if we use the client as like below, using:

import (
    "xxxx/client"
)

config := shu.Config{
    VerifyCert:  false,
    Server:      []string{"http://localhost:5000"},
    HTTP:        shu.HTTP{},
    Trace:       false,
    TraceFile:   "",
    Marshaler:   nil,
    Unmarshaler: nil,
}
client.GetBundle().SetOption(
    shu.WithConfig(&config))

authClient := client.GetAuthClient()
userLogin := client.UserLogin{
    Name:     "damon",
    Password: "chen",
}
resp, err := authClient.Login(userLogin)
if err != nil {
    ...
}

...

basic convention

• you should use the following code to generate api file

//go:generate shugen definition.go -o client.go

The generate.go is your api definition, and the client.go is the file which you want to generate.

• define a global variable, and the variable name must be defined bundle

var (
    bundle = shu.NewBundle()
)

• using bundle.Client in init function to define your client api

bundle.Client(shu.Client{
		Name: "auth",   // define client name
		APIs: []*shu.API{
			{
				Name:     "login",  // define api name with also for function name in generate
				Path:     "/api/v1/login",
				Method:   shu.POST,
				Params:   UserLogin{},      // api request param
				Response: UserLoginResp{},  // api response body
			},
		},
	},
	)

• last you should have an init and given a bundle client function

func init() {
	...
	bundle.Init()
}

func GetBundle() *shu.Bundle {
    return bundle
}

usage

TODO

• base running
• generate tool
  • basic
  • format generate file
• write doc
• rest api parser and generator
• http client pool for performance
• reflect performance