From d7f3fca111221b65046abd00037339a8c9386f21 Mon Sep 17 00:00:00 2001 From: xushiwei Date: Mon, 11 Mar 2024 00:25:35 +0800 Subject: [PATCH] Update manual.md --- doc/manual.md | 156 +++++++++++++++++++++----------------------------- 1 file changed, 64 insertions(+), 92 deletions(-) diff --git a/doc/manual.md b/doc/manual.md index ea30e41..c74b553 100644 --- a/doc/manual.md +++ b/doc/manual.md @@ -19,23 +19,25 @@ demo in Go ([hello.go](../demo/hello/hello.go)): ```go import "github.com/goplus/yap" -y := yap.New() -y.GET("/", func(ctx *yap.Context) { - ctx.TEXT(200, "text/html", `Hello, YAP!`) -}) -y.GET("/p/:id", func(ctx *yap.Context) { - ctx.JSON(200, yap.H{ - "id": ctx.Param("id"), +func main() { + y := yap.New() + y.GET("/", func(ctx *yap.Context) { + ctx.TEXT(200, "text/html", `Hello, YAP!`) }) -}) -y.Run(":8080") + y.GET("/p/:id", func(ctx *yap.Context) { + ctx.JSON(200, yap.H{ + "id": ctx.Param("id"), + }) + }) + y.Run(":8080") +} ``` -demo in Go+ classfile ([main.yap](../demo/classfile_hello/main.yap)): +demo in Go+ classfile v1 ([main.yap](../demo/classfile_hello/main.yap)): ```go get "/", ctx => { - ctx.html `Hello, YAP!` + ctx.html `Hello, YAP!` } get "/p/:id", ctx => { ctx.json { @@ -46,6 +48,21 @@ get "/p/:id", ctx => { run "localhost:8080" ``` +demo in Go+ classfile v2 ([get.yap](../demo/classfile2_hello/get.yap), [get_p_#id.yap](../demo/classfile2_hello/get_p_%23id.yap)): + +* [get.yap](../demo/classfile2_hello/get.yap): + +```go +html `Hello, YAP!` +``` + +* [get_p_#id.yap](../demo/classfile2_hello/get_p_%23id.yap): + +```coffee +json { + "id": ${id}, +} +``` ### Static files @@ -53,16 +70,19 @@ Static files server demo in Go: ```go y := yap.New(os.DirFS(".")) + y.Static("/foo", y.FS("public")) y.Static("/") // means: y.Static("/", y.FS("static")) + y.Run(":8080") ``` -Static files server demo in Go+ classfile ([staticfile_yap.gox](../demo/classfile_static/staticfile_yap.gox)): +Static files server demo in Go+ classfile ([main.yap](../demo/classfile2_static/main.yap)): ```go static "/foo", FS("public") static "/" + run ":8080" ``` @@ -75,6 +95,7 @@ static "/", fs.http("https://goplus.org"), false // false means not allow to red run ":8888" ``` + ### YAP Template demo in Go ([blog.go](../demo/blog/blog.go), [article_yap.html](../demo/blog/yap/article_yap.html)): @@ -97,7 +118,7 @@ y.GET("/p/:id", func(ctx *yap.Context) { y.Run(":8080") ``` -demo in Go+ classfile ([blog_yap.gox](../demo/classfile_blog/blog_yap.gox), [article_yap.html](../demo/classfile_blog/yap/article_yap.html)): +demo in Go+ classfile v1 ([main.yap](../demo/classfile_blog/blog_yap.gox)): ```go get "/p/:id", ctx => { @@ -106,107 +127,58 @@ get "/p/:id", ctx => { } } -run ":8080" +run ":8888" ``` -### YAP Test Framework - -Suppose we have a web server named `foo` ([demo/foo/foo_yap.gox](../ytest/demo/foo/foo_yap.gox)): +demo in Go+ classfile v2 ([get_p_#id.yap](../demo/classfile2_blog/get_p_%23id.yap), [article_yap.html](../demo/classfile2_blog/yap/article_yap.html)): ```go -get "/p/:id", ctx => { - ctx.json { - "id": ctx.param("id"), - } +yap "article", { + "id": ${id}, } - -run ":8080" ``` -Then we create a yaptest file ([demo/foo/foo_ytest.gox](../ytest/demo/foo/foo_ytest.gox)): -```go -mock "foo.com", new(foo) - -run "test get /p/$id", => { - id := "123" - get "http://foo.com/p/${id}" - ret 200 - json { - "id": id, - } -} -``` +### YAP Test Framework -The directive `mock` creates the `foo` server by [mockhttp](https://pkg.go.dev/github.com/qiniu/x/mockhttp). Then we call the directive `run` to run a subtest. +This classfile has the file suffix `_ytest.gox`. -You can change the directive `mock` to `testServer` (see [demo/foo/bar_ytest.gox](../ytest/demo/foo/bar_ytest.gox)), and keep everything else unchanged: +Suppose we have a web server ([foo/get_p_#id.yap](../ytest/demo/foo/get_p_%23id.yap)): ```go -testServer "foo.com", new(foo) - -run "test get /p/$id", => { - id := "123" - get "http://foo.com/p/${id}" - ret 200 - json { - "id": id, - } +json { + "id": ${id}, } ``` -The directive `testServer` creates the `foo` server by [net/http/httptest](https://pkg.go.dev/net/http/httptest#NewServer) and obtained a random port as the service address. Then it calls the directive [host](https://pkg.go.dev/github.com/goplus/yap/ytest#App.Host) to map the random service address to `foo.com`. This makes all other code no need to changed. +Then we create a yaptest file ([foo/foo_ytest.gox](../ytest/demo/foo/foo_ytest.gox)): -We can change this example more complicated: +```go +mock "foo.com", new(AppV2) // name of any YAP v2 web server is `AppV2` -```coffee -host "https://example.com", "http://localhost:8080" -testauth := oauth2("...") - -run "urlWithVar", => { - id := "123" - get "https://example.com/p/${id}" - ret - echo "code:", resp.code - echo "body:", resp.body +id := "123" +get "http://foo.com/p/${id}" +ret 200 +json { + "id": id, } +``` -run "matchWithVar", => { - code := Var(int) - id := "123" - get "https://example.com/p/${id}" - ret code - echo "code:", code - match code, 200 -} +The directive `mock` creates the web server by [mockhttp](https://pkg.go.dev/github.com/qiniu/x/mockhttp). Then we write test code directly. -run "postWithAuth", => { - id := "123" - title := "title" - author := "author" - post "https://example.com/p/${id}" - auth testauth - json { - "title": title, - "author": author, - } - ret 200 # match resp.code, 200 - echo "body:", resp.body -} +You can change the directive `mock` to `testServer` (see [foo/bar_ytest.gox](../ytest/demo/foo/bar_ytest.gox)), and keep everything else unchanged: -run "matchJsonObject", => { - title := Var(string) - author := Var(string) - id := "123" - get "https://example.com/p/${id}" - ret 200 - json { - "title": title, - "author": author, - } - echo "title:", title - echo "author:", author +```go +testServer "foo.com", new(AppV2) + +id := "123" +get "http://foo.com/p/${id}" +ret 200 +json { + "id": id, } ``` +The directive `testServer` creates the web server by [net/http/httptest](https://pkg.go.dev/net/http/httptest#NewServer) and obtained a random port as the service address. Then it calls the directive [host](https://pkg.go.dev/github.com/goplus/yap/ytest#App.Host) to map the random service address to `foo.com`. This makes all other code no need to changed. + For more details, see [yaptest - Go+ HTTP Test Framework](../ytest).