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