harsp

package module
v0.0.0-...-8177fe1 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2019 License: MIT Imports: 5 Imported by: 0

README

Harsp

Harsp can quickly construct the Http Response structure, standardize the structure of the returned data, and currently supports five data formats: JSON, JSONP, XML, html, and text.

1. API Rsp

The returned data structure of the API is special. All API data is added with errCode and the corresponding message to indicate the result of this API request.

  • JSON

    You can use this example when you want to return a successful JSON response data:

    harsp.JSON{Data:map[string]interface{}{"a":"b"}}.Success(w)

    This will return:

    {"code":"0","data":{"a":"b"},"msg":"Success"}

    If you want to respond to a wrong data, then you can use this example:

    harsp.JSON{Rc:harsp.RetCode{Code:"10001", Msg:"err example"}}.Failed(w)

    This will return:

    {"code":"10001","msg":"err example"}

    When returning an error response, you don't need Data to pass in. If you pass in Data, Harsp will process it and return it together, but this is not the normal practice. Since you think this is a bad request, why should you return data ?

  • JSONP

    The data returned by JSONP is basically the same as the JSON data format, only the MIME type is modified, and the function output of the callback is added.

    Success:

    harsp.JSONP{Data:map[string]interface{}{"a":"b"}, Callback:"Jsonp"}.Success(w)

    This will return:

    Jsonp({"code":"0","data":{"a":"b"},"msg":"Success"})

    Failed:

    harsp.JSONP{Rc:harsp.RetCode{Code:"10002", Msg:"err example"}, Callback:"Jsonp"}.Failed(w)

    This will return:

    Jsonp({"code":"10002","msg":"err example"})

  • XML

    Harsp's API response data is defined as the map[string]interface{} structure type. The official xml package does not support this type of xml conversion. Therefore, Harsp applies the open source package of github.com/ryanwx/mxj to complete the API response. Data map structure to xml conversion.

    Success:

    harsp.XML{Data:map[string]interface{}{"a":"b", "list":[]string{"aa", "bb"}}}.Success(w)

    This will return:

    <doc>
    <code>0</code>
    <data>
        <a>b</a>
        <list>aa</list>
        <list>bb</list>
    </data>
    <msg>Success</msg>
</doc>

    Failed:

    harsp.XML{Rc:harsp.RetCode{Code:"10002", Msg:"err example"}}.Failed(w)

    This will return:

    <doc>
    <code>10002</code>
    <msg>err example</msg>
</doc>

    In the xml conversion, the root tag is defined as doc. If it is a list structure, the tag is defined as named tag, and the map is tagged by key.

  • Return data default fill function

    DefaultPadding func(RetCode, interface{}) map[string]interface{} = defaultContentPadding

func defaultContentPadding(rc RetCode, d interface{}) map[string]interface{} {
	data := map[string]interface{}{
		"code": rc.Code,
		"msg":  rc.Msg,
	}

	if nil != d {
		data["data"] = d
	}

	return data
}

    Harsp defines a default return data fill function in the package. If you want to customize the fill function, you can reset the DefaultPadding value when you start your application. Once the settings are complete, Harsp returns the API class data. The returned data will be populated with the func corresponding to this value

  • Return error code structure

    type RetCode struct {
	// return error code
	// use this code to show this request result.
	Code string

	// return error message
	// this is request result message.
	Msg  string
}

    The return data structure of Harsp's API is contracted to return the code of the request structure and the corresponding message unless Harsp returns a non-200 status code. Harsp specifies the structure of the return data error code. You can customize the error code of their own application and pass in their own defined error code when returning data.

  • Default success response error code

    SuccessRet = RetCode{Code: "0", Msg: "Success"}

    When the server returns a response indicating success, no additional error code is required. Harsp defines a default error code indicating success. Of course, you can reset the value.

2. Html OR text

The html OR Text data is returned without an error code, and Harsp will return the string completely without any padding.

  • Html

    harsp.HTML{Data:"<h2>Hello World!</h2>"}.Send(w)

    This will return:

    Hello World!

  • Text

    harsp.TEXT{Data:"<h2>Hello World!</h2>"}.Send(w)

    This will return:

    <h2>Hello World!</h2>

All data return methods will return the http.ResponseWriter object of the current operation, so you can call the method to write data to the response body multiple times during the lifetime of your request, for html OR text data format The return is meaningful. If it is API data, Harsp recommends that all of it be written to the response data at once.

Write response data multiple times:

Send:

harsp.HTML{Data:"<h2>Hello World!</h2>"}.Send(w)
harsp.TEXT{Data:"<h2>Hello World!</h2>"}.Send(w)

This will return:

Hello World!
Hello World!

License

Harsp is under the MIT license. See the LICENSE file for details.

Thanks

  • xml transport open resource: mxj

Documentation

Index

Constants

View Source 
const (
	MimeText  = "text/plain; charset=utf-8"
	MimeXML   = "text/xml; charset=utf-8"
	MimeHtml  = "text/html; charset=utf-8"
	MimeJson  = "application/json; charset=utf-8"
	MimeJsonP = "text/plain; charset=utf-8"
)

TODO: add support of more charset.

Variables

View Source 
var DefaultPadding func(RetCode, interface{}) map[string]interface{} = defaultContentPadding

default response content padding func. if you want define your content padding format, you can set variable with your padding func. only JSON|XML|JSONP will use the padding func

View Source 
var (
	// when Harsp write the byte to the response, when it failed, this error will return in any response func.
	ErrWriteFailed = errors.New("failed to write message to http response")
)
View Source 
var (
	// this is default success code, you also can reset the variable what you want be, but this must be RetCode struct.
	SuccessRet = RetCode{Code: "0", Msg: "Success"}
)

Functions

func BadRequest 

func BadRequest(w http.ResponseWriter, msg string) error

this func return a http response with status code 400 this means the http client request is Invalid, it's usually point the request param.

func Forbidden 

func Forbidden(w http.ResponseWriter, msg string) error

this func return a http response with status code 403. which means the client don't has the power to get the resource.

func MethodNotAllowed 

func MethodNotAllowed(w http.ResponseWriter, msg string) error

this func return a http response with status code 406 this means the http request method is not allowed, witch usually used in the application of RESTful.

func NotFound 

func NotFound(w http.ResponseWriter, msg string) error

this func return a http response with status code 404. witch means the resource what the client want is don't exist.

func RequestTimeout 

func RequestTimeout(w http.ResponseWriter, msg string) error

this func return a http response with status code 408 this means the http request is timeout

func UnAuthorized 

func UnAuthorized(w http.ResponseWriter, msg string) error

this func return a http response with status code 401 this means the client is unauthorized, like UnLogin.

Types

type ApiRspWriter 

type ApiRspWriter interface {

	// when you want to return a success msg to the http client, you can use this func.
	// this func use the default errCode string 0, if you want change the default value,
	// your must to set the package variable of SuccessCode to a new value,
	// you can do it when you start your application, once you do that, it will always affected.
	// @param: w http.ResponseWriter, all the data will use the writer write into the response
	// @param: data interface, this is the response content
	// @return： w http.ResponseWriter
	Success(http.ResponseWriter) (http.ResponseWriter, error)

	// when you want to return a failed msg to the http client, you can use this func.
	// you can define your errCode in your application, when you use this func to send a failed response,
	// you can assign which errCode you wish to return.
	// @param: w http.ResponseWriter, all the data will use the writer write into the response
	// @param: data interface, this is the response content
	// @return： w http.ResponseWriter
	Failed(http.ResponseWriter) (http.ResponseWriter, error)
	// contains filtered or unexported methods
}

type HTML 

type HTML struct {
	Data string
}

func (HTML) Send 

func (this HTML) Send(w http.ResponseWriter) (http.ResponseWriter, error)

this func implements the rspWriter func Send. this Send a Json data to the client.

type JSON 

type JSON struct {
	Rc RetCode

	Data interface{}
}

func (JSON) Failed 

func (this JSON) Failed(w http.ResponseWriter) (http.ResponseWriter, error)

this implements the rspWriter func Failed. this func send a json data to the client with the errCode.

func (JSON) Success 

func (this JSON) Success(w http.ResponseWriter) (http.ResponseWriter, error)

this implements the rspWriter func Success. this Send a Success response to the client with the default success Json data format or you set the default success Json data format.

type JSONP 

type JSONP struct {
	Rc RetCode

	Data interface{}

	// when you use jsonp data response, you must be set a callback func.
	Callback string
}

func (JSONP) Failed 

func (this JSONP) Failed(w http.ResponseWriter) (http.ResponseWriter, error)

when you want to return a failed msg to the http client, you can use this func. you can define your errCode in your application, when you use this func to send a failed response, you can assign which errCode you wish to return. @param: w http.ResponseWriter, all the data will use the writer write into the response @param: data interface, this is the response content @return： w http.ResponseWriter

func (JSONP) Success 

func (this JSONP) Success(w http.ResponseWriter) (http.ResponseWriter, error)

when you want to return a success msg to the http client, you can use this func. this func use the default errCode string 0, if you want change the default value, your must to set the package variable of SuccessCode to a new value, you can do it when you start your application, once you do that, it will always affected. @param: w http.ResponseWriter, all the data will use the writer write into the response @param: data interface, this is the response content @return： w http.ResponseWriter

type RetCode 

type RetCode struct {
	// return error code
	// use this code to show this request result.
	Code string

	// return error message
	// this is request result message.
	Msg string
}

all the response errCode and msg must be the RetCode struct.

type TEXT 

type TEXT struct {
	Data string
}

func (TEXT) Send 

func (this TEXT) Send(w http.ResponseWriter) (http.ResponseWriter, error)

this func implements the rspWriter func Send. this Send a Json data to the client.

type TextRspWriter 

type TextRspWriter interface {
	// send a text data, which contains text|html.
	// it returns the writer, then you can use the writer continue to write.
	// @param: w http.ResponseWriter, all the data will use the writer write into the response
	// @param: data string, this is the response content
	// @return： w http.ResponseWriter
	Send(http.ResponseWriter) (http.ResponseWriter, error)
}

type XML 

type XML struct {
	Rc RetCode

	Data interface{}
}

func (XML) Failed 

func (this XML) Failed(w http.ResponseWriter) (http.ResponseWriter, error)

when you want to return a failed msg to the http client, you can use this func. you can define your errCode in your application, when you use this func to send a failed response, you can assign which errCode you wish to return. @param: w http.ResponseWriter, all the data will use the writer write into the response @param: data interface, this is the response content @return： w http.ResponseWriter

func (XML) Success 

func (this XML) Success(w http.ResponseWriter) (http.ResponseWriter, error)

when you want to return a success msg to the http client, you can use this func. this func use the default errCode string 0, if you want change the default value, your must to set the package variable of SuccessCode to a new value, you can do it when you start your application, once you do that, it will always affected. @param: w http.ResponseWriter, all the data will use the writer write into the response @param: data interface, this is the response content @return： w http.ResponseWriter

Source Files

View all Source files

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.