GH-5 add a query directive to pull values from querystring params

[davidalpert]

No description provided.

[ggicci]

Thanks a lot for this PR. Could you please confirm that if the form and query directives work the same? If so, I think we can make query as an alias of form.

[davidalpert]

I was surprised to learn that the unit test I added still passed after using the form directive.

I am going to confirm that this works also in the web project I experienced the initial challenge, then will update this pr to demonstrate that the form tag works to parse querystring values.

[ggicci]

I think the name form may have caused the misunderstanding. In Go world, if we use net/http package to get query parameters, the corresponding method is Request.FormValue. That's why I named the directive asform.

Now through your case I think that maybe other people have the same problem like yours. Thus the name query should be more intuitive.

If the name was the root cause leading to the misunderstanding. I propose to make an alias of the original form directive. Which can be called query.

[ggicci]

I've reviewed this PR these days and have a conclusion here:

The form directive extracts values from Request.Form which contains the parsed form data, including both the URL field's query parameters and the PATCH, POST, or PUT form data. It's populated by Request.ParseForm() and the most important is:

Request body parameters take precedence over URL query string values in r.Form.

Though it looks like the proposed query directive can be replaced with the form directive to archieve the same function, it still has subtle differences:

The query directive ONLY treats the values from the URL query string as the valid input. Thus the following request may cause unexpected behaviour when using the form directive:

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"net/url"
	"strings"
)

func PrintInput(rw http.ResponseWriter, r *http.Request) {
	r.ParseForm()
	fmt.Printf("ContentType: %#v\n", r.Header.Get("Content-Type"))
	fmt.Printf("Form: %#v\n", r.Form)
	fmt.Printf("Query: %#v\n", r.URL.Query())
}

func main() {
	postForm := url.Values{}
	postForm.Add("is_member", "false")
	r2 := httptest.NewRequest(
		"POST",
		"http://example.com/users?page=5&page_size=20&is_member=true",
		strings.NewReader(postForm.Encode()),
	)

	r2.Header.Add("Content-Type", "application/x-www-form-urlencoded")
	w2 := httptest.NewRecorder()
	PrintInput(w2, r2)
}

Output:

ContentType: "application/x-www-form-urlencoded"
Form: url.Values{"is_member":[]string{"false", "true"}, "page":[]string{"5"}, "page_size":[]string{"20"}}
                                        ^^^^^ (x)
Query: url.Values{"is_member":[]string{"true"}, "page":[]string{"5"}, "page_size":[]string{"20"}}
                                         ^^^^ (√)

Finally, I would like to merge this pull request and give some detail explanations in the documentation. @davidalpert Thanks again :)

[ggicci]

I think query is used more frequently than the other directives. It's better to be documented at the first place. And we can tell something about the difference between form and query or simply link to the conversation of this PR.

[davidalpert]

Thank you for considering this PR and explaining that Request.ParseForm() already merges Request.Url.Query() into r.Form and the nuance about precedence (where form body values will override querystring values). Perhaps we can update the documentation to make it extra clear that the form directive already includes querystring values.

By having the query directive in this PR pull from r.URL.Query() instead of the merged r.Form collection, I understand that it would bind to values from the querystring but ignore any values posted in the form.

Documentation can be tricky to get right while iterating through a pull request. Would you like to update the readme directly in this branch? Feel free to take this PR, adjust it as you like, and merge it when you feel it is complete.

[davidalpert]

@ggicci would you be willing to add a hacktoberfest-accepted label to this PR?

I am participating in Digital Ocean's Hacktoberfest this year and that label will allow this PR to be recognized as a Hacktoberfest contribution.

[ggicci]

sure