comment update for package ghttp

net/ghttp/ghttp_request_auth.go

@@ -14,18 +14,6 @@ import (
 	"github.com/gogf/gf/encoding/gbase64"
 )
 
-// setBasicAuth sets the http basic authentication tips.
-func (r *Request) setBasicAuth(tips ...string) {
-	realm := ""
-	if len(tips) > 0 && tips[0] != "" {
-		realm = tips[0]
-	} else {
-		realm = "Need Login"
-	}
-	r.Response.Header().Set("WWW-Authenticate", fmt.Sprintf(`Basic realm="%s"`, realm))
-	r.Response.WriteHeader(http.StatusUnauthorized)
-}
-
 // BasicAuth enables the http basic authentication feature with given passport and password
 // and asks client for authentication. It returns true if authentication success, else returns
 // false if failure.
@@ -62,5 +50,16 @@ func (r *Request) BasicAuth(user, pass string, tips ...string) bool {
 		r.Response.WriteStatus(http.StatusForbidden)
 		return false
 	}
-	return false
+}
+
+// setBasicAuth sets the http basic authentication tips.
+func (r *Request) setBasicAuth(tips ...string) {
+	realm := ""
+	if len(tips) > 0 && tips[0] != "" {
+		realm = tips[0]
+	} else {
+		realm = "Need Login"
+	}
+	r.Response.Header().Set("WWW-Authenticate", fmt.Sprintf(`Basic realm="%s"`, realm))
+	r.Response.WriteHeader(http.StatusUnauthorized)
 }

net/ghttp/ghttp_request_hook.go

@@ -1,23 +0,0 @@
-// Copyright 2017 gf Author(https://github.com/gogf/gf). All Rights Reserved.
-//
-// This Source Code Form is subject to the terms of the MIT License.
-// If a copy of the MIT was not distributed with this file,
-// You can obtain one at https://github.com/gogf/gf.
-
-package ghttp
-
-// 获得当前请求，指定类型的的钩子函数列表
-func (r *Request) getHookHandlers(hook string) []*handlerParsedItem {
-	if !r.hasHookHandler {
-		return nil
-	}
-	parsedItems := make([]*handlerParsedItem, 0, 4)
-	for _, v := range r.handlers {
-		if v.handler.hookName != hook {
-			continue
-		}
-		item := v
-		parsedItems = append(parsedItems, item)
-	}
-	return parsedItems
-}

net/ghttp/ghttp_request_middleware.go

@@ -24,6 +24,7 @@ type Middleware struct {
 }
 
 // Next calls the next workflow handler.
+// It's an important function controlling the workflow of the server request execution.
 func (m *Middleware) Next() {
 	var item *handlerParsedItem
 	var loop = true

net/ghttp/ghttp_request_param.go

@@ -32,7 +32,7 @@ var (
 // to given struct, and then calls gvalid.CheckStruct validating the struct according
 // to the validation tag of the struct.
 //
-// See GetStruct, gvalid.CheckStruct.
+// See r.GetStruct, gvalid.CheckStruct.
 func (r *Request) Parse(pointer interface{}) error {
 	if err := r.GetStruct(pointer); err != nil {
 		return err
@@ -45,7 +45,7 @@ func (r *Request) Parse(pointer interface{}) error {
 
 // Get is alias of GetRequest, which is one of the most commonly used functions for
 // retrieving parameter.
-// See GetRequest.
+// See r.GetRequest.
 func (r *Request) Get(key string, def ...interface{}) interface{} {
 	return r.GetRequest(key, def...)
 }
@@ -58,17 +58,20 @@ func (r *Request) GetVar(key string, def ...interface{}) *gvar.Var {
 
 // GetRaw is alias of GetBody.
 // See GetBody.
+// Deprecated.
 func (r *Request) GetRaw() []byte {
 	return r.GetBody()
 }
 
 // GetRawString is alias of GetBodyString.
 // See GetBodyString.
+// Deprecated.
 func (r *Request) GetRawString() string {
 	return r.GetBodyString()
 }
 
-// GetRaw retrieves and returns request body content as bytes.
+// GetBody retrieves and returns request body content as bytes.
+// It can be called multiple times retrieving the same body content.
 func (r *Request) GetBody() []byte {
 	if r.bodyContent == nil {
 		r.bodyContent, _ = ioutil.ReadAll(r.Body)
@@ -77,92 +80,127 @@ func (r *Request) GetBody() []byte {
 	return r.bodyContent
 }
 
-// GetRawString retrieves and returns request body content as string.
+// GetBodyString retrieves and returns request body content as string.
+// It can be called multiple times retrieving the same body content.
 func (r *Request) GetBodyString() string {
-	return gconv.UnsafeBytesToStr(r.GetRaw())
+	return gconv.UnsafeBytesToStr(r.GetBody())
 }
 
 // GetJson parses current request content as JSON format, and returns the JSON object.
 // Note that the request content is read from request BODY, not from any field of FORM.
 func (r *Request) GetJson() (*gjson.Json, error) {
-	return gjson.LoadJson(r.GetRaw())
+	return gjson.LoadJson(r.GetBody())
 }
 
+// GetString is an alias and convenient function for GetRequestString.
+// See GetRequestString.
 func (r *Request) GetString(key string, def ...interface{}) string {
 	return r.GetRequestString(key, def...)
 }
 
+// GetBool is an alias and convenient function for GetRequestBool.
+// See GetRequestBool.
 func (r *Request) GetBool(key string, def ...interface{}) bool {
 	return r.GetRequestBool(key, def...)
 }
 
+// GetInt is an alias and convenient function for GetRequestInt.
+// See GetRequestInt.
 func (r *Request) GetInt(key string, def ...interface{}) int {
 	return r.GetRequestInt(key, def...)
 }
 
+// GetInt32 is an alias and convenient function for GetRequestInt32.
+// See GetRequestInt32.
 func (r *Request) GetInt32(key string, def ...interface{}) int32 {
 	return r.GetRequestInt32(key, def...)
 }
 
+// GetInt64 is an alias and convenient function for GetRequestInt64.
+// See GetRequestInt64.
 func (r *Request) GetInt64(key string, def ...interface{}) int64 {
 	return r.GetRequestInt64(key, def...)
 }
 
+// GetInts is an alias and convenient function for GetRequestInts.
+// See GetRequestInts.
 func (r *Request) GetInts(key string, def ...interface{}) []int {
 	return r.GetRequestInts(key, def...)
 }
 
+// GetUint is an alias and convenient function for GetRequestUint.
+// See GetRequestUint.
 func (r *Request) GetUint(key string, def ...interface{}) uint {
 	return r.GetRequestUint(key, def...)
 }
 
+// GetUint32 is an alias and convenient function for GetRequestUint32.
+// See GetRequestUint32.
 func (r *Request) GetUint32(key string, def ...interface{}) uint32 {
 	return r.GetRequestUint32(key, def...)
 }
 
+// GetUint64 is an alias and convenient function for GetRequestUint64.
+// See GetRequestUint64.
 func (r *Request) GetUint64(key string, def ...interface{}) uint64 {
 	return r.GetRequestUint64(key, def...)
 }
 
+// GetFloat32 is an alias and convenient function for GetRequestFloat32.
+// See GetRequestFloat32.
 func (r *Request) GetFloat32(key string, def ...interface{}) float32 {
 	return r.GetRequestFloat32(key, def...)
 }
 
+// GetFloat64 is an alias and convenient function for GetRequestFloat64.
+// See GetRequestFloat64.
 func (r *Request) GetFloat64(key string, def ...interface{}) float64 {
 	return r.GetRequestFloat64(key, def...)
 }
 
+// GetFloats is an alias and convenient function for GetRequestFloats.
+// See GetRequestFloats.
 func (r *Request) GetFloats(key string, def ...interface{}) []float64 {
 	return r.GetRequestFloats(key, def...)
 }
 
+// GetArray is an alias and convenient function for GetRequestArray.
+// See GetRequestArray.
 func (r *Request) GetArray(key string, def ...interface{}) []string {
 	return r.GetRequestArray(key, def...)
 }
 
+// GetStrings is an alias and convenient function for GetRequestStrings.
+// See GetRequestStrings.
 func (r *Request) GetStrings(key string, def ...interface{}) []string {
 	return r.GetRequestStrings(key, def...)
 }
 
+// GetInterfaces is an alias and convenient function for GetRequestInterfaces.
+// See GetRequestInterfaces.
 func (r *Request) GetInterfaces(key string, def ...interface{}) []interface{} {
 	return r.GetRequestInterfaces(key, def...)
 }
 
+// GetMap is an alias and convenient function for GetRequestMap.
+// See GetRequestMap.
 func (r *Request) GetMap(def ...map[string]interface{}) map[string]interface{} {
 	return r.GetRequestMap(def...)
 }
 
+// GetMapStrStr is an alias and convenient function for GetRequestMapStrStr.
+// See GetRequestMapStrStr.
 func (r *Request) GetMapStrStr(def ...map[string]interface{}) map[string]string {
 	return r.GetRequestMapStrStr(def...)
 }
 
-// GetStruct is alias of GetRequestToStruct.
-// See GetRequestToStruct.
+// GetStruct is an alias and convenient function for GetRequestStruct.
+// See GetRequestStruct.
 func (r *Request) GetStruct(pointer interface{}, mapping ...map[string]string) error {
 	return r.GetRequestStruct(pointer, mapping...)
 }
 
-// GetToStruct is alias of GetRequestToStruct.
+// GetToStruct is an alias and convenient function for GetRequestStruct.
 // See GetRequestToStruct.
 // Deprecated.
 func (r *Request) GetToStruct(pointer interface{}, mapping ...map[string]string) error {
@@ -184,7 +222,7 @@ func (r *Request) parseQuery() {
 	}
 }
 
-// ParseRaw parses the request raw data into r.rawMap.
+// parseBody parses the request raw data into r.rawMap.
 // Note that it also supports JSON data from client request.
 func (r *Request) parseBody() {
 	if r.parsedBody {
@@ -289,7 +327,7 @@ func (r *Request) GetMultipartForm() *multipart.Form {
 	return r.MultipartForm
 }
 
-// GetMultipartFiles returns the post files array.
+// GetMultipartFiles parses and returns the post files array.
 // Note that the request form should be type of multipart.
 func (r *Request) GetMultipartFiles(name string) []*multipart.FileHeader {
 	form := r.GetMultipartForm()

net/ghttp/ghttp_request_param_ctx.go

@@ -11,8 +11,9 @@ import (
 	"github.com/gogf/gf/container/gvar"
 )
 
-// Context retrieves and returns the request's context.
+// Context is alias for function GetCtx.
 // This function overwrites the http.Request.Context function.
+// See GetCtx.
 func (r *Request) Context() context.Context {
 	if r.context == nil {
 		r.context = r.Request.Context()
@@ -20,13 +21,14 @@ func (r *Request) Context() context.Context {
 	return r.context
 }
 
-// GetCtx is alias for function Context.
-// See Context.
+// GetCtx retrieves and returns the request's context.
 func (r *Request) GetCtx() context.Context {
 	return r.Context()
 }
 
 // GetCtxVar retrieves and returns a Var with given key name.
+// The optional parameter <def> specifies the default value of the Var if given <key>
+// does not exist in the context.
 func (r *Request) GetCtxVar(key interface{}, def ...interface{}) *gvar.Var {
 	value := r.Context().Value(key)
 	if value == nil && len(def) > 0 {

net/ghttp/ghttp_request_param_form.go

@@ -22,8 +22,7 @@ func (r *Request) SetForm(key string, value interface{}) {
 }
 
 // GetForm retrieves and returns parameter <key> from form.
-// It returns <def> if <key> does not exist in the form.
-// It returns nil if <def> is not passed.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetForm(key string, def ...interface{}) interface{} {
 	r.parseForm()
 	if len(r.formMap) > 0 {
@@ -37,66 +36,98 @@ func (r *Request) GetForm(key string, def ...interface{}) interface{} {
 	return nil
 }
 
+// GetFormVar retrieves and returns parameter <key> from form as Var.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormVar(key string, def ...interface{}) *gvar.Var {
 	return gvar.New(r.GetForm(key, def...))
 }
 
+// GetFormString retrieves and returns parameter <key> from form as string.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormString(key string, def ...interface{}) string {
 	return r.GetFormVar(key, def...).String()
 }
 
+// GetFormBool retrieves and returns parameter <key> from form as bool.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormBool(key string, def ...interface{}) bool {
 	return r.GetFormVar(key, def...).Bool()
 }
 
+// GetFormInt retrieves and returns parameter <key> from form as int.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormInt(key string, def ...interface{}) int {
 	return r.GetFormVar(key, def...).Int()
 }
 
+// GetFormInt32 retrieves and returns parameter <key> from form as int32.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormInt32(key string, def ...interface{}) int32 {
 	return r.GetFormVar(key, def...).Int32()
 }
 
+// GetFormInt64 retrieves and returns parameter <key> from form as int64.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormInt64(key string, def ...interface{}) int64 {
 	return r.GetFormVar(key, def...).Int64()
 }
 
+// GetFormInts retrieves and returns parameter <key> from form as []int.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormInts(key string, def ...interface{}) []int {
 	return r.GetFormVar(key, def...).Ints()
 }
 
+// GetFormUint retrieves and returns parameter <key> from form as uint.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormUint(key string, def ...interface{}) uint {
 	return r.GetFormVar(key, def...).Uint()
 }
 
+// GetFormUint32 retrieves and returns parameter <key> from form as uint32.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormUint32(key string, def ...interface{}) uint32 {
 	return r.GetFormVar(key, def...).Uint32()
 }
 
+// GetFormUint64 retrieves and returns parameter <key> from form as uint64.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormUint64(key string, def ...interface{}) uint64 {
 	return r.GetFormVar(key, def...).Uint64()
 }
 
+// GetFormFloat32 retrieves and returns parameter <key> from form as float32.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormFloat32(key string, def ...interface{}) float32 {
 	return r.GetFormVar(key, def...).Float32()
 }
 
+// GetFormFloat64 retrieves and returns parameter <key> from form as float64.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormFloat64(key string, def ...interface{}) float64 {
 	return r.GetFormVar(key, def...).Float64()
 }
 
+// GetFormFloats retrieves and returns parameter <key> from form as []float64.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormFloats(key string, def ...interface{}) []float64 {
 	return r.GetFormVar(key, def...).Floats()
 }
 
+// GetFormArray retrieves and returns parameter <key> from form as []string.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormArray(key string, def ...interface{}) []string {
 	return r.GetFormVar(key, def...).Strings()
 }
 
+// GetFormStrings retrieves and returns parameter <key> from form as []string.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormStrings(key string, def ...interface{}) []string {
 	return r.GetFormVar(key, def...).Strings()
 }
 
+// GetFormInterfaces retrieves and returns parameter <key> from form as []interface{}.
+// It returns <def> if <key> does not exist in the form and <def> is given, or else it returns nil.
 func (r *Request) GetFormInterfaces(key string, def ...interface{}) []interface{} {
 	return r.GetFormVar(key, def...).Interfaces()
 }

net/ghttp/ghttp_request_param_post.go

@@ -16,8 +16,8 @@ import (
 // It returns <def> if <key> does not exist in neither form nor body.
 // It returns nil if <def> is not passed.
 //
-// Note that if there're multiple parameters with the same name, the parameters are retrieved and overwrote
-// in order of priority: form > body.
+// Note that if there're multiple parameters with the same name, the parameters are retrieved
+// and overwrote in order of priority: form > body.
 //
 // Deprecated.
 func (r *Request) GetPost(key string, def ...interface{}) interface{} {

net/ghttp/ghttp_request_param_query.go

@@ -23,11 +23,11 @@ func (r *Request) SetQuery(key string, value interface{}) {
 }
 
 // GetQuery retrieves and returns parameter with given name <key> from query string
-// and request body. It returns <def> if <key> does not exist in the query. It returns nil
-// if <def> is not passed.
+// and request body. It returns <def> if <key> does not exist in the query and <def> is given,
+// or else it returns nil.
 //
-// Note that if there're multiple parameters with the same name, the parameters are retrieved and overwrote
-// in order of priority: query > body.
+// Note that if there're multiple parameters with the same name, the parameters are retrieved
+// and overwrote in order of priority: query > body.
 func (r *Request) GetQuery(key string, def ...interface{}) interface{} {
 	r.parseQuery()
 	if len(r.queryMap) > 0 {

net/ghttp/ghttp_server_router_hook.go

@@ -63,6 +63,22 @@ func (s *Server) callHookHandler(hook string, r *Request) {
 	}
 }
 
+// 获得当前请求，指定类型的的钩子函数列表
+func (r *Request) getHookHandlers(hook string) []*handlerParsedItem {
+	if !r.hasHookHandler {
+		return nil
+	}
+	parsedItems := make([]*handlerParsedItem, 0, 4)
+	for _, v := range r.handlers {
+		if v.handler.hookName != hook {
+			continue
+		}
+		item := v
+		parsedItems = append(parsedItems, item)
+	}
+	return parsedItems
+}
+
 // 友好地调用方法
 func (s *Server) niceCallHookHandler(f HandlerFunc, r *Request) (err interface{}) {
 	defer func() {

net/ghttp/ghttp_server_service_controller.go

@@ -87,7 +87,7 @@ func (s *Server) doBindController(
 					pkgPath, ctlName, methodName, v.Method(i).Type().String())
 			} else {
 				// 否则只是Debug提示
-				s.Logger().Debugf(`ignore route method: %s.%s.%s defined as "%s", no match "func()"`,
+				s.Logger().Debugf(`ignore route method: %s.%s.%s defined as "%s", no match "func()" for controller registry`,
 					pkgPath, ctlName, methodName, v.Method(i).Type().String())
 			}
 			continue

net/ghttp/ghttp_server_service_object.go

@@ -96,7 +96,7 @@ func (s *Server) doBindObject(
 			} else {
 				// 否则只是Debug提示
 				s.Logger().Debugf(
-					`ignore route method: %s.%s.%s defined as "%s", no match "func(*ghttp.Request)"`,
+					`ignore route method: %s.%s.%s defined as "%s", no match "func(*ghttp.Request)" for object registry`,
 					pkgPath, objName, methodName, v.Method(i).Type().String(),
 				)
 			}

util/gutil/gutil.go

@@ -16,21 +16,13 @@ func Throw(exception interface{}) {
 	panic(exception)
 }
 
-// TryCatch implements try...catch... logistics.
+// TryCatch implements try...catch... logistics using internal panic...recover.
 func TryCatch(try func(), catch ...func(exception interface{})) {
-	if len(catch) > 0 {
-		// If <catch> is given, it's used to handle the exception.
-		defer func() {
-			if e := recover(); e != nil {
-				catch[0](e)
-			}
-		}()
-	} else {
-		// If no <catch> function passed, it filters the exception.
-		defer func() {
-			recover()
-		}()
-	}
+	defer func() {
+		if e := recover(); e != nil && len(catch) > 0 {
+			catch[0](e)
+		}
+	}()
 	try()
 }