Repository navigation
Expand file tree
/
Copy pathREADME.MD
More file actions
151 lines (100 loc) · 4.38 KB
/
Copy pathREADME.MD
File metadata and controls
151 lines (100 loc) · 4.38 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# wenci
基于 GoFrame v2 的单体仓库模板,已内置本地 MySQL(Docker Compose)、用户注册/登录与账户信息示例接口。
**运行与工程化以 [GoFrame 官方文档](https://goframe.org/docs/cli) 为准**:开发启动使用 `gf run main.go`;代码生成使用 `gf gen ctrl` / `gf gen dao` 等(本仓库 `hack/hack.mk` 中的 `make ctrl`、`make dao` 与之对应)。`cmd/tools/watchctrl` 为可选本地辅助(监听 `api` 后调 `gf gen ctrl`),不属于框架自带流程。
## 本地依赖
- Go:以你本机 `go.mod` 为准
- [GoFrame CLI `gf`](https://goframe.org/docs/cli):`go install github.com/gogf/gf/cmd/gf/v2@latest`,并将 `$(go env GOPATH)/bin` 加入 `PATH`
- Docker:本地 MySQL(Windows / macOS 常用 Docker Desktop;Linux 可用 Docker Engine + Compose 插件)
## 新环境 / 换机(最小步骤)
仓库不绑定某台机器;换电脑后按顺序即可(**macOS / Linux / Windows 通用**,命令路径按系统习惯写)。
1. `git clone` 后进入项目根目录
2. `docker compose up -d` 启动 MySQL(需本机 **3306** 未被占用,或与 `manifest/config/config.yaml` 中 `link` 一致)
3. `go mod tidy`(或至少能成功 `go build`)
4. 按需设置 `WENCI_JWT_KEY`(见下节)
5. `gf run main.go`
## 启动 MySQL(本地)
```bash
docker compose up -d
```
连接信息(例如 Navicat):
- 主机:`127.0.0.1`
- 端口:`3306`
- 用户名:`root`
- 密码:`root123456`
- 数据库:`wenci`
> 数据库连接配置在 `manifest/config/config.yaml` 的 `database.default.link`。
## JWT 密钥(多机/多环境必读)
签名与校验使用 `internal/consts` 中的 `JwtKey`:
- 优先读取环境变量 **`WENCI_JWT_KEY`**;未设置时使用占位值 `dev-change-me`(仅适合本机随便跑)。
- **同一套环境里**,签发 token 的机器与校验 token 的机器必须使用**相同**的密钥,否则登录后访问鉴权接口会失败。
- **不要把真实密钥写进仓库**;生产环境请用环境变量或密钥管理服务注入。
Windows PowerShell(当前终端有效):
```powershell
$env:WENCI_JWT_KEY = "你的随机长密钥"
gf run main.go
```
macOS / Linux(当前 shell 有效,zsh / bash 等):
```bash
export WENCI_JWT_KEY='你的随机长密钥'
gf run main.go
```
持久化请用各系统自带方式(如 Windows `setx`、macOS `launchctl`、Linux systemd 用户环境等),勿把密钥写入仓库。
Windows 持久(新开终端生效,示例):
```powershell
setx WENCI_JWT_KEY "你的随机长密钥"
```
## 启动服务(本地)
```bash
gf run main.go
```
默认监听:`http://127.0.0.1:8000`
- OpenAPI:`/api.json`
- Swagger:`/swagger`
## 接口示例
路由前缀均为 **`/v1`**。需要鉴权的接口在 `internal/cmd/cmd.go` 中挂了 `middleware.Auth`。
### Swagger 鉴权(推荐)
访问 `http://127.0.0.1:8000/swagger`,点击右上角 **Authorize**,选择 `AuthToken`:
- 推荐填写:`Bearer <登录返回的 token>`
- 兼容旧调用:直接填写 `<token>`(未来可以按需下线)
### 用户注册(无需鉴权)
- 路径:`POST /v1/users/register`
- Body:
```json
{
"username": "test001",
"password": "12345678",
"email": "test001@example.com"
}
```
### 用户登录(无需鉴权)
- 路径:`POST /v1/users/login`
- Body:
```json
{
"username": "test001",
"password": "12345678"
}
```
- 响应中的 `token` 用于后续鉴权。
### 账户信息(需要鉴权)
- 路径:`GET /v1/account/info`
- Header(推荐):`Authorization: Bearer <登录返回的 token>`
- Header(兼容旧调用):`Authorization: <登录返回的 token>`(未来可以按需下线)
### 单词(需要鉴权)
- 创建:`POST /v1/words`
- 更新:`PUT /v1/words/{id}`
- Header 同上(推荐 Bearer)
## 开发:自动生成 controller
官方方式:在项目根执行 `gf gen ctrl`,或使用 `make ctrl`(见 `hack/hack.mk`,会先检查 `gf` CLI)。
可选:修改 `api/**/v1/*.go` 后启动监听工具自动执行 `gf gen ctrl`(带防抖)。说明见 `cmd/tools/watchctrl/README.md`。
PowerShell(项目根目录):
```powershell
go run .\cmd\tools\watchctrl
```
macOS / Linux:
```bash
go run ./cmd/tools/watchctrl
```
## 参考
- GoFrame Quick Start:`https://goframe.org/quick`
- GoFrame CLI(`gf run`、`gf gen`、`gf build` 等):`https://goframe.org/docs/cli`