profilesvc

package
v0.4.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2023 License: MIT Imports: 15 Imported by: 0

README

profilesvc

Let's take profilesvc as an example, see how we can generate the endpoint/http code based on the interface Service.

Prerequisites

  1. Adjust the Service interface

    • Add a meaningful name to each input/output parameter, to get more human-readable field names in the corresponding request/response structs.
    • Add kun-specific comments (i.e. comments start with "// @kun") in a OAS-inspired format, to describe the properties of the exposed HTTP APIs.

  2. Customize HTTP encoders and decoders

  3. List business errors for generating failure responses in OAS (Optional)

Generate the code

  1. Use the kungen command

    Just run:

    $ kungen ./service.go Service

  2. Use go:generate

    Add //go:generate kungen ./service.go Service before the Service interface, then run:

    $ go generate

Code generated:

Test the server

Run the Profile server:

$ go run cmd/server/main.go
2020/08/05 20:37:36 transport=HTTP addr=:8080

Create a Profile:

$ curl -i -X POST http://localhost:8080/profiles -H "Content-Type: application/json" -d '{"profile": {"id": "1234", "name": "kun"}}'
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 08 May 2020 02:22:22 GMT
Content-Length: 3

{}

Get the profile you just created:

$ curl -i http://localhost:8080/profiles/1234
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 08 May 2020 02:22:25 GMT
Content-Length: 39

{"profile":{"id":"1234","name":"kun"}}

Generate OAS Documentation

$ curl http://localhost:8080/api > api.yaml

For those who want to preview the final generated documentation, see the pre-generated file api.yaml.

Test the client

Run the Profile client:

$ go run cmd/client/main.go
2020/08/05 20:37:45 GetProfile ok: {ID:1 Name:profile1 Addresses:[]}
2020/08/05 20:37:45 GetAddress ok: {ID:4 Location:address4}
2020/08/05 20:37:45 GetAddresses ok: [{ID:4 Location:address4}]

Run tests:

$ go test -v -race

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInconsistentIDs = errors.New("inconsistent IDs")
	ErrAlreadyExists   = errors.New("already exists")
	ErrNotFound        = errors.New("not found")
)

Functions

func GetFailures 

func GetFailures(name string) map[error]interface{}

func MakeEndpointOfDeleteAddress 

func MakeEndpointOfDeleteAddress(s Service) endpoint.Endpoint

MakeEndpointOfDeleteAddress creates the endpoint for s.DeleteAddress.

func MakeEndpointOfDeleteProfile 

func MakeEndpointOfDeleteProfile(s Service) endpoint.Endpoint

MakeEndpointOfDeleteProfile creates the endpoint for s.DeleteProfile.

func MakeEndpointOfGetAddress 

func MakeEndpointOfGetAddress(s Service) endpoint.Endpoint

MakeEndpointOfGetAddress creates the endpoint for s.GetAddress.

func MakeEndpointOfGetAddresses 

func MakeEndpointOfGetAddresses(s Service) endpoint.Endpoint

MakeEndpointOfGetAddresses creates the endpoint for s.GetAddresses.

func MakeEndpointOfGetProfile 

func MakeEndpointOfGetProfile(s Service) endpoint.Endpoint

MakeEndpointOfGetProfile creates the endpoint for s.GetProfile.

func MakeEndpointOfPatchProfile 

func MakeEndpointOfPatchProfile(s Service) endpoint.Endpoint

MakeEndpointOfPatchProfile creates the endpoint for s.PatchProfile.

func MakeEndpointOfPostAddress 

func MakeEndpointOfPostAddress(s Service) endpoint.Endpoint

MakeEndpointOfPostAddress creates the endpoint for s.PostAddress.

func MakeEndpointOfPostProfile 

func MakeEndpointOfPostProfile(s Service) endpoint.Endpoint

MakeEndpointOfPostProfile creates the endpoint for s.PostProfile.

func MakeEndpointOfPutProfile 

func MakeEndpointOfPutProfile(s Service) endpoint.Endpoint

MakeEndpointOfPutProfile creates the endpoint for s.PutProfile.

func NewCodecs 

func NewCodecs() *httpcodec.DefaultCodecs

func NewHTTPRouter 

func NewHTTPRouter(svc Service, codecs httpcodec.Codecs, opts ...httpoption.Option) chi.Router

func NewSchema 

func NewSchema() *oas2.ResponseSchema

func OASv2APIDoc 

func OASv2APIDoc(schema oas2.Schema) string

func ValidateDeleteAddressRequest 

func ValidateDeleteAddressRequest(newSchema func(*DeleteAddressRequest) validating.Schema) httpoption.Validator

ValidateDeleteAddressRequest creates a validator for DeleteAddressRequest.

func ValidateDeleteProfileRequest 

func ValidateDeleteProfileRequest(newSchema func(*DeleteProfileRequest) validating.Schema) httpoption.Validator

ValidateDeleteProfileRequest creates a validator for DeleteProfileRequest.

func ValidateGetAddressRequest 

func ValidateGetAddressRequest(newSchema func(*GetAddressRequest) validating.Schema) httpoption.Validator

ValidateGetAddressRequest creates a validator for GetAddressRequest.

func ValidateGetAddressesRequest 

func ValidateGetAddressesRequest(newSchema func(*GetAddressesRequest) validating.Schema) httpoption.Validator

ValidateGetAddressesRequest creates a validator for GetAddressesRequest.

func ValidateGetProfileRequest 

func ValidateGetProfileRequest(newSchema func(*GetProfileRequest) validating.Schema) httpoption.Validator

ValidateGetProfileRequest creates a validator for GetProfileRequest.

func ValidatePatchProfileRequest 

func ValidatePatchProfileRequest(newSchema func(*PatchProfileRequest) validating.Schema) httpoption.Validator

ValidatePatchProfileRequest creates a validator for PatchProfileRequest.

func ValidatePostAddressRequest 

func ValidatePostAddressRequest(newSchema func(*PostAddressRequest) validating.Schema) httpoption.Validator

ValidatePostAddressRequest creates a validator for PostAddressRequest.

func ValidatePostProfileRequest 

func ValidatePostProfileRequest(newSchema func(*PostProfileRequest) validating.Schema) httpoption.Validator

ValidatePostProfileRequest creates a validator for PostProfileRequest.

func ValidatePutProfileRequest 

func ValidatePutProfileRequest(newSchema func(*PutProfileRequest) validating.Schema) httpoption.Validator

ValidatePutProfileRequest creates a validator for PutProfileRequest.

Types

type Address 

type Address struct {
	ID       string `json:"id"`
	Location string `json:"location,omitempty"`
}

Address is a field of a user profile. ID should be unique within the profile (at a minimum).

type Codec 

type Codec struct {
	httpcodec.JSON
}

func (Codec) EncodeFailureResponse 

func (c Codec) EncodeFailureResponse(w http.ResponseWriter, err error) error

type DeleteAddressRequest 

type DeleteAddressRequest struct {
	Id        string `json:"-"`
	AddressID string `json:"-"`
}

type DeleteAddressResponse 

type DeleteAddressResponse struct {
	Err error `json:"-"`
}

func (*DeleteAddressResponse) Body 

func (r *DeleteAddressResponse) Body() interface{}

func (*DeleteAddressResponse) Failed 

func (r *DeleteAddressResponse) Failed() error

Failed implements endpoint.Failer.

type DeleteProfileRequest 

type DeleteProfileRequest struct {
	Id string `json:"-"`
}

type DeleteProfileResponse 

type DeleteProfileResponse struct {
	Err error `json:"-"`
}

func (*DeleteProfileResponse) Body 

func (r *DeleteProfileResponse) Body() interface{}

func (*DeleteProfileResponse) Failed 

func (r *DeleteProfileResponse) Failed() error

Failed implements endpoint.Failer.

type GetAddressRequest 

type GetAddressRequest struct {
	Id        string `json:"-"`
	AddressID string `json:"-"`
}

type GetAddressResponse 

type GetAddressResponse struct {
	Address Address `json:"address"`
	Err     error   `json:"-"`
}

func (*GetAddressResponse) Body 

func (r *GetAddressResponse) Body() interface{}

func (*GetAddressResponse) Failed 

func (r *GetAddressResponse) Failed() error

Failed implements endpoint.Failer.

type GetAddressesRequest 

type GetAddressesRequest struct {
	Id string `json:"-"`
}

type GetAddressesResponse 

type GetAddressesResponse struct {
	Addresses []Address `json:"addresses"`
	Err       error     `json:"-"`
}

func (*GetAddressesResponse) Body 

func (r *GetAddressesResponse) Body() interface{}

func (*GetAddressesResponse) Failed 

func (r *GetAddressesResponse) Failed() error

Failed implements endpoint.Failer.

type GetProfileRequest 

type GetProfileRequest struct {
	Id string `json:"-"`
}

type GetProfileResponse 

type GetProfileResponse struct {
	Profile Profile `json:"profile"`
	Err     error   `json:"-"`
}

func (*GetProfileResponse) Body 

func (r *GetProfileResponse) Body() interface{}

func (*GetProfileResponse) Failed 

func (r *GetProfileResponse) Failed() error

Failed implements endpoint.Failer.

type HTTPClient 

type HTTPClient struct {
	// contains filtered or unexported fields
}

func NewHTTPClient 

func NewHTTPClient(codecs httpcodec.Codecs, httpClient *http.Client, baseURL string) (*HTTPClient, error)

func (*HTTPClient) DeleteAddress 

func (c *HTTPClient) DeleteAddress(ctx context.Context, id string, addressID string) (err error)

func (*HTTPClient) DeleteProfile 

func (c *HTTPClient) DeleteProfile(ctx context.Context, id string) (err error)

func (*HTTPClient) GetAddress 

func (c *HTTPClient) GetAddress(ctx context.Context, id string, addressID string) (address Address, err error)

func (*HTTPClient) GetAddresses 

func (c *HTTPClient) GetAddresses(ctx context.Context, id string) (addresses []Address, err error)

func (*HTTPClient) GetProfile 

func (c *HTTPClient) GetProfile(ctx context.Context, id string) (profile Profile, err error)

func (*HTTPClient) PatchProfile 

func (c *HTTPClient) PatchProfile(ctx context.Context, id string, profile Profile) (err error)

func (*HTTPClient) PostAddress 

func (c *HTTPClient) PostAddress(ctx context.Context, id string, address Address) (err error)

func (*HTTPClient) PostProfile 

func (c *HTTPClient) PostProfile(ctx context.Context, profile Profile) (err error)

func (*HTTPClient) PutProfile 

func (c *HTTPClient) PutProfile(ctx context.Context, id string, profile Profile) (err error)

type PatchProfileRequest 

type PatchProfileRequest struct {
	Id      string  `json:"-"`
	Profile Profile `json:"profile"`
}

type PatchProfileResponse 

type PatchProfileResponse struct {
	Err error `json:"-"`
}

func (*PatchProfileResponse) Body 

func (r *PatchProfileResponse) Body() interface{}

func (*PatchProfileResponse) Failed 

func (r *PatchProfileResponse) Failed() error

Failed implements endpoint.Failer.

type PostAddressRequest 

type PostAddressRequest struct {
	Id      string  `json:"-"`
	Address Address `json:"address"`
}

type PostAddressResponse 

type PostAddressResponse struct {
	Err error `json:"-"`
}

func (*PostAddressResponse) Body 

func (r *PostAddressResponse) Body() interface{}

func (*PostAddressResponse) Failed 

func (r *PostAddressResponse) Failed() error

Failed implements endpoint.Failer.

type PostProfileRequest 

type PostProfileRequest struct {
	Profile Profile `json:"profile"`
}

type PostProfileResponse 

type PostProfileResponse struct {
	Err error `json:"-"`
}

func (*PostProfileResponse) Body 

func (r *PostProfileResponse) Body() interface{}

func (*PostProfileResponse) Failed 

func (r *PostProfileResponse) Failed() error

Failed implements endpoint.Failer.

type Profile 

type Profile struct {
	ID        string    `json:"id"`
	Name      string    `json:"name,omitempty"`
	Addresses []Address `json:"addresses,omitempty"`
}

Profile represents a single user profile. ID should be globally unique.

type PutProfileRequest 

type PutProfileRequest struct {
	Id      string  `json:"-"`
	Profile Profile `json:"profile"`
}

type PutProfileResponse 

type PutProfileResponse struct {
	Err error `json:"-"`
}

func (*PutProfileResponse) Body 

func (r *PutProfileResponse) Body() interface{}

func (*PutProfileResponse) Failed 

func (r *PutProfileResponse) Failed() error

Failed implements endpoint.Failer.

type Service 

type Service interface {
	//kun:op POST /profiles
	PostProfile(ctx context.Context, profile Profile) (err error)

	//kun:op GET /profiles/{id}
	GetProfile(ctx context.Context, id string) (profile Profile, err error)

	//kun:op PUT /profiles/{id}
	PutProfile(ctx context.Context, id string, profile Profile) (err error)

	//kun:op PATCH /profiles/{id}
	PatchProfile(ctx context.Context, id string, profile Profile) (err error)

	//kun:op DELETE /profiles/{id}
	DeleteProfile(ctx context.Context, id string) (err error)

	//kun:op GET /profiles/{id}/addresses
	GetAddresses(ctx context.Context, id string) (addresses []Address, err error)

	//kun:op GET /profiles/{id}/addresses/{addressID}
	GetAddress(ctx context.Context, id string, addressID string) (address Address, err error)

	//kun:op POST /profiles/{id}/addresses
	PostAddress(ctx context.Context, id string, address Address) (err error)

	//kun:op DELETE /profiles/{id}/addresses/{addressID}
	DeleteAddress(ctx context.Context, id string, addressID string) (err error)
}

Service is a simple CRUD interface for user profiles.

func NewInmemService 

func NewInmemService() Service

Source Files

View all Source files

Directories

Path Synopsis
cmd
client
server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.