Skip to content

Commit 5819f5b

Browse files
committed
docs: add comprehensive example documentation
- Add session example with README - Add routing example with README - Add README for bind, config, middleware, mock, router examples - Update main README with complete index and feature examples - All examples now have: - Running instructions - Testing commands - Code examples - API reference 🦖 Generated by 小源 (OpenClaw AI Assistant)
1 parent cd4a377 commit 5819f5b

10 files changed

Lines changed: 1063 additions & 1 deletion

File tree

example/README.md

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@ go run main.go
1919
| [middleware](./middleware) | Logging, auth, CORS | ★★☆ |
2020
| [session](./session) | Session management | ★★☆ |
2121
| [group](./group) | Route grouping with 404 handlers | ★★☆ |
22+
| [bind](./bind) | Data binding (form, JSON) | ★★☆ |
23+
| [config](./config) | Configuration files | ★★☆ |
24+
| [router](./router) | Advanced routing | ★★☆ |
25+
| [mock](./mock) | Mock mode for testing | ★★☆ |
2226

2327
## Feature Examples
2428

@@ -85,11 +89,27 @@ app.HttpServer.GET("/login", func(ctx dotweb.Context) error {
8589
})
8690
```
8791

92+
### 6. Data Binding
93+
```go
94+
type User struct {
95+
Name string `json:"name" form:"name"`
96+
Age int `json:"age" form:"age"`
97+
}
98+
99+
app.HttpServer.POST("/users", func(ctx dotweb.Context) error {
100+
user := new(User)
101+
if err := ctx.Bind(user); err != nil {
102+
return err
103+
}
104+
return ctx.WriteString(fmt.Sprintf("Created: %s", user.Name))
105+
})
106+
```
107+
88108
## Running Examples
89109

90110
```bash
91111
# Run any example
92-
cd example/group
112+
cd example/session
93113
go run main.go
94114

95115
# With hot reload (using air)

example/bind/README.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Data Binding Example
2+
3+
This example demonstrates how to bind request data to Go structs in DotWeb.
4+
5+
## Features
6+
7+
- Bind form data to struct
8+
- Bind JSON body to struct
9+
- Custom binder implementation
10+
- Using JSON tags for binding
11+
12+
## Running
13+
14+
```bash
15+
cd example/bind
16+
go run main.go
17+
```
18+
19+
## Testing
20+
21+
### Bind Form Data (POST)
22+
23+
```bash
24+
# Using JSON tag for binding
25+
curl -X POST http://localhost:8080/ \
26+
-d 'UserName=Alice&Sex=1'
27+
# Output: TestBind [no error] &{Alice 1}
28+
```
29+
30+
### Bind Query Parameters (GET)
31+
32+
```bash
33+
curl "http://localhost:8080/getbind?user=Bob&sex=2"
34+
# Output: GetBind [no error] &{Bob 2}
35+
```
36+
37+
### Bind JSON Body (POST)
38+
39+
```bash
40+
curl -X POST http://localhost:8080/jsonbind \
41+
-H "Content-Type: application/json" \
42+
-d '{"user":"Charlie","sex":1}'
43+
# Output: PostBind [no error] &{Charlie 1}
44+
```
45+
46+
## Binding Methods
47+
48+
### 1. Auto Bind (Form/JSON)
49+
50+
```go
51+
type UserInfo struct {
52+
UserName string `json:"user" form:"user"`
53+
Sex int `json:"sex" form:"sex"`
54+
}
55+
56+
func handler(ctx dotweb.Context) error {
57+
user := new(UserInfo)
58+
if err := ctx.Bind(user); err != nil {
59+
return err
60+
}
61+
// user.UserName, user.Sex are populated
62+
return nil
63+
}
64+
```
65+
66+
### 2. Bind JSON Body
67+
68+
```go
69+
func handler(ctx dotweb.Context) error {
70+
user := new(UserInfo)
71+
if err := ctx.BindJsonBody(user); err != nil {
72+
return err
73+
}
74+
return nil
75+
}
76+
```
77+
78+
### 3. Custom Binder
79+
80+
```go
81+
// Implement dotweb.Binder interface
82+
type userBinder struct{}
83+
84+
func (b *userBinder) Bind(i interface{}, ctx dotweb.Context) error {
85+
// Custom binding logic
86+
return nil
87+
}
88+
89+
func (b *userBinder) BindJsonBody(i interface{}, ctx dotweb.Context) error {
90+
// Custom JSON binding logic
91+
return nil
92+
}
93+
94+
// Register custom binder
95+
app.HttpServer.SetBinder(newUserBinder())
96+
```
97+
98+
## Configuration
99+
100+
### Enable JSON Tag
101+
102+
```go
103+
// Use JSON tags instead of form tags
104+
app.HttpServer.SetEnabledBindUseJsonTag(true)
105+
```
106+
107+
## API Reference
108+
109+
| Method | Description |
110+
|--------|-------------|
111+
| `ctx.Bind(struct)` | Auto bind from form/JSON |
112+
| `ctx.BindJsonBody(struct)` | Bind from JSON body |
113+
| `app.HttpServer.SetBinder(binder)` | Set custom binder |
114+
| `app.HttpServer.SetEnabledBindUseJsonTag(bool)` | Use JSON tags |
115+
116+
## Notes
117+
118+
- Default tag name is `form`
119+
- Enable `SetEnabledBindUseJsonTag(true)` to use JSON tags
120+
- Custom binder allows implementing your own binding logic
121+
- Supports JSON, XML, and form data content types

example/config/README.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Configuration Example
2+
3+
This example demonstrates how to configure DotWeb using different config file formats.
4+
5+
## Config Files
6+
7+
| File | Format | Description |
8+
|------|--------|-------------|
9+
| `dotweb.json` | JSON | JSON configuration |
10+
| `dotweb.yaml` | YAML | YAML configuration |
11+
| `dotweb.conf` | INI | INI-style configuration |
12+
| `userconf.xml` | XML | XML configuration |
13+
14+
## Running
15+
16+
```bash
17+
cd example/config
18+
go run main.go
19+
```
20+
21+
## Configuration Methods
22+
23+
### 1. Classic Mode (with config file)
24+
25+
```go
26+
// Load config from directory
27+
app := dotweb.Classic("/path/to/config")
28+
29+
// Or use current directory
30+
app := dotweb.Classic(file.GetCurrentDirectory())
31+
```
32+
33+
Classic mode automatically loads:
34+
- `dotweb.json`
35+
- `dotweb.yaml`
36+
- `dotweb.conf`
37+
38+
### 2. Programmatic Configuration
39+
40+
```go
41+
app := dotweb.New()
42+
43+
// Enable features
44+
app.SetEnabledLog(true)
45+
app.SetDevelopmentMode()
46+
47+
// Server configuration
48+
app.HttpServer.SetEnabledSession(true)
49+
app.HttpServer.SetEnabledGzip(true)
50+
app.HttpServer.SetMaxBodySize(10 * 1024 * 1024) // 10MB
51+
```
52+
53+
## Config File Structure
54+
55+
### JSON (`dotweb.json`)
56+
57+
```json
58+
{
59+
"App": {
60+
"EnabledLog": true,
61+
"LogPath": "./logs"
62+
},
63+
"HttpServer": {
64+
"Port": 8080,
65+
"EnabledSession": true,
66+
"EnabledGzip": true,
67+
"MaxBodySize": 10485760
68+
}
69+
}
70+
```
71+
72+
### YAML (`dotweb.yaml`)
73+
74+
```yaml
75+
App:
76+
EnabledLog: true
77+
LogPath: ./logs
78+
79+
HttpServer:
80+
Port: 8080
81+
EnabledSession: true
82+
EnabledGzip: true
83+
MaxBodySize: 10485760
84+
```
85+
86+
### INI (`dotweb.conf`)
87+
88+
```ini
89+
[App]
90+
EnabledLog = true
91+
LogPath = ./logs
92+
93+
[HttpServer]
94+
Port = 8080
95+
EnabledSession = true
96+
EnabledGzip = true
97+
MaxBodySize = 10485760
98+
```
99+
100+
## Common Settings
101+
102+
| Setting | Method | Description |
103+
|---------|--------|-------------|
104+
| Log | `app.SetEnabledLog(true)` | Enable logging |
105+
| Log Path | `app.SetLogPath("./logs")` | Log directory |
106+
| Dev Mode | `app.SetDevelopmentMode()` | Development mode |
107+
| Prod Mode | `app.SetProductionMode()` | Production mode |
108+
| Session | `app.HttpServer.SetEnabledSession(true)` | Enable session |
109+
| Gzip | `app.HttpServer.SetEnabledGzip(true)` | Enable gzip compression |
110+
| Max Body | `app.HttpServer.SetMaxBodySize(bytes)` | Max request body size |
111+
112+
## Notes
113+
114+
- Config files are loaded in order: JSON → YAML → INI
115+
- Programmatic config overrides file config
116+
- Use `dotweb.Classic()` for quick setup with defaults
117+
- Use `dotweb.New()` for full control

0 commit comments

Comments
 (0)