github.com/goplus/yap@v0.8.1/README.md (about) 1 yap - Yet Another Go/Go+ HTTP Web Framework 2 ====== 3 4 [![Build Status](https://github.com/goplus/yap/actions/workflows/go.yml/badge.svg)](https://github.com/goplus/yap/actions/workflows/go.yml) 5 [![Go Report Card](https://goreportcard.com/badge/github.com/goplus/yap)](https://goreportcard.com/report/github.com/goplus/yap) 6 [![GitHub release](https://img.shields.io/github/v/tag/goplus/yap.svg?label=release)](https://github.com/goplus/yap/releases) 7 [![Coverage Status](https://codecov.io/gh/goplus/yap/branch/main/graph/badge.svg)](https://codecov.io/gh/goplus/yap) 8 [![GoDoc](https://pkg.go.dev/badge/github.com/goplus/yap.svg)](https://pkg.go.dev/github.com/goplus/yap) 9 [![Language](https://img.shields.io/badge/language-Go+-blue.svg)](https://github.com/goplus/gop) 10 11 This repo contains three [Go+ classfiles](https://github.com/goplus/gop/blob/main/doc/classfile.md). They are [yap](#yap-http-web-framework) (a HTTP Web Framework), [yaptest](ytest) (a HTTP Test Framework) and [ydb](ydb) (a Go+ Database Framework). 12 13 The classfile [yap](#yap-http-web-framework) has the file suffix `.yap`. The classfile [yaptest](ytest) has the file suffix `_ytest.gox`. And the classfile [ydb](ydb) has the file suffix `_ydb.gox`. 14 15 Before using `yap`, `yaptest` or `ydb`, you need to add `github.com/goplus/yap` to `go.mod`: 16 17 ```sh 18 gop get github.com/goplus/yap@latest 19 ``` 20 21 For more details, see [YAP Framework Manual](doc/manual.md). 22 23 24 ### How to use in Go+ 25 26 First let us initialize a hello project: 27 28 ```sh 29 gop mod init hello 30 ``` 31 32 Then we have it reference a classfile called `yap` as the HTTP Web Framework: 33 34 ```sh 35 gop get github.com/goplus/yap@latest 36 ``` 37 38 Create a file named [get.yap](demo/classfile2_hello/get.yap) with the following content: 39 40 ```go 41 html `<html><body>Hello, YAP!</body></html>` 42 ``` 43 44 Execute the following commands: 45 46 ```sh 47 gop mod tidy 48 gop run . 49 ``` 50 51 A simplest web program is running now. At this time, if you visit http://localhost:8080, you will get: 52 53 ``` 54 Hello, YAP! 55 ``` 56 57 58 ### yap: HTTP Web Framework 59 60 This classfile has the file suffix `.yap`. 61 62 63 #### Router and Parameters 64 65 YAP uses filenames to define routes. `get.yap`'s route is `get "/"` (GET homepage), and `get_p_#id.yap`'s route is `get "/p/:id"` (In fact, the filename can also be `get_p_:id.yap`, but it is not recommended because `:` is not allowed to exist in filenames under Windows). 66 67 Let's create a file named [get_p_#id.yap](demo/classfile2_hello/get_p_%23id.yap) with the following content: 68 69 ```coffee 70 json { 71 "id": ${id}, 72 } 73 ``` 74 75 Execute `gop run .` and visit http://localhost:8080/p/123, you will get: 76 77 ``` 78 {"id": "123"} 79 ``` 80 81 82 #### YAP Template 83 84 In most cases, we don't use the `html` directive to generate html pages, but use the `yap` template engine. See [get_p_#id.yap](demo/classfile2_blog/get_p_%23id.yap): 85 86 ```coffee 87 yap "article", { 88 "id": ${id}, 89 } 90 ``` 91 92 It means finding a template called `article` to render. See [yap/article_yap.html](demo/classfile2_blog/yap/article_yap.html): 93 94 ```html 95 <html> 96 <head><meta charset="utf-8"/></head> 97 <body>Article {{.id}}</body> 98 </html> 99 ``` 100 101 #### Run at specified address 102 103 By default the YAP server runs on `localhost:8080`, but you can change it in [main.yap](demo/classfile2_blog/main.yap) file: 104 105 ```coffee 106 run ":8888" 107 ``` 108 109 110 #### Static files 111 112 Static files server demo ([main.yap](demo/classfile2_static/main.yap)): 113 114 ```coffee 115 static "/foo", FS("public") 116 static "/" 117 118 run ":8080" 119 ``` 120 121 122 ### yaptest: HTTP Test Framework 123 124 [yaptest](ytest) is a web server testing framework. This classfile has the file suffix `_ytest.gox`. 125 126 Suppose we have a web server ([foo/get_p_#id.yap](ytest/demo/foo/get_p_%23id.yap)): 127 128 ```go 129 json { 130 "id": ${id}, 131 } 132 ``` 133 134 Then we create a yaptest file ([foo/foo_ytest.gox](ytest/demo/foo/foo_ytest.gox)): 135 136 ```go 137 mock "foo.com", new(AppV2) // name of any YAP v2 web server is `AppV2` 138 139 id := "123" 140 get "http://foo.com/p/${id}" 141 ret 200 142 json { 143 "id": id, 144 } 145 ``` 146 147 The directive `mock` creates the web server by [mockhttp](https://pkg.go.dev/github.com/qiniu/x/mockhttp). Then we write test code directly. 148 149 You can change the directive `mock` to `testServer` (see [foo/bar_ytest.gox](ytest/demo/foo/bar_ytest.gox)), and keep everything else unchanged: 150 151 ```go 152 testServer "foo.com", new(AppV2) 153 154 id := "123" 155 get "http://foo.com/p/${id}" 156 ret 200 157 json { 158 "id": id, 159 } 160 ``` 161 162 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. 163 164 For more details, see [yaptest - Go+ HTTP Test Framework](ytest). 165 166 167 ### ydb: Database Framework 168 169 This classfile has the file suffix `_ydb.gox`. 170 171 TODO