Skip to content

Commit 7617f67

Browse files
appleboyappleboy
committed
docs: add multilingual support and Chinese translations to documentation
- Add language selection links to the top of the documentation - Introduce a Simplified Chinese (zh-CN) README with usage instructions and feature overview - Introduce a Traditional Chinese (zh-TW) README with usage instructions and feature overview Signed-off-by: Bo-Yi Wu <[email protected]>
1 parent 06ac89f commit 7617f67

File tree

3 files changed

+474
-0
lines changed

3 files changed

+474
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Gin JWT Middleware
22

3+
[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
4+
35
[![Run Tests](https://github.com/appleboy/gin-jwt/actions/workflows/go.yml/badge.svg)](https://github.com/appleboy/gin-jwt/actions/workflows/go.yml)
46
[![GitHub tag](https://img.shields.io/github/tag/appleboy/gin-jwt.svg)](https://github.com/appleboy/gin-jwt/releases)
57
[![GoDoc](https://godoc.org/github.com/appleboy/gin-jwt?status.svg)](https://godoc.org/github.com/appleboy/gin-jwt)

‎README.zh-CN.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Gin JWT 中间件
2+
3+
[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
4+
5+
[![Run Tests](https://github.com/appleboy/gin-jwt/actions/workflows/go.yml/badge.svg)](https://github.com/appleboy/gin-jwt/actions/workflows/go.yml)
6+
[![GitHub tag](https://img.shields.io/github/tag/appleboy/gin-jwt.svg)](https://github.com/appleboy/gin-jwt/releases)
7+
[![GoDoc](https://godoc.org/github.com/appleboy/gin-jwt?status.svg)](https://godoc.org/github.com/appleboy/gin-jwt)
8+
[![Go Report Card](https://goreportcard.com/badge/github.com/appleboy/gin-jwt)](https://goreportcard.com/report/github.com/appleboy/gin-jwt)
9+
[![codecov](https://codecov.io/gh/appleboy/gin-jwt/branch/master/graph/badge.svg)](https://codecov.io/gh/appleboy/gin-jwt)
10+
[![codebeat badge](https://codebeat.co/badges/c4015f07-df23-4c7c-95ba-9193a12e14b1)](https://codebeat.co/projects/github-com-appleboy-gin-jwt)
11+
[![Sourcegraph](https://sourcegraph.com/github.com/appleboy/gin-jwt/-/badge.svg)](https://sourcegraph.com/github.com/appleboy/gin-jwt?badge)
12+
13+
一个强大且灵活的 [Gin](https://github.com/gin-gonic/gin) Web 框架的 JWT 认证中间件，基于 [jwt-go](https://github.com/golang-jwt/jwt) 实现。
14+
轻松为你的 Gin 应用添加登录、Token 刷新与授权功能。
15+
16+
---
17+
18+
## 目录
19+
20+
- [Gin JWT 中间件](#gin-jwt-中间件)
21+
- [目录](#目录)
22+
- [功能特色](#功能特色)
23+
- [安全性注意事项](#安全性注意事项)
24+
- [安装](#安装)
25+
- [使用 Go Modules（推荐）](#使用-go-modules推荐)
26+
- [快速开始示例](#快速开始示例)
27+
- [Demo](#demo)
28+
- [登录](#登录)
29+
- [刷新 Token](#刷新-token)
30+
- [Hello World](#hello-world)
31+
- [授权示例](#授权示例)
32+
- [Cookie Token](#cookie-token)
33+
- [登录流程（LoginHandler）](#登录流程loginhandler)
34+
- [需要 JWT Token 的端点（MiddlewareFunc）](#需要-jwt-token-的端点middlewarefunc)
35+
- [登出流程（LogoutHandler）](#登出流程logouthandler)
36+
- [刷新流程（RefreshHandler）](#刷新流程refreshhandler)
37+
- [登录失败、Token 错误或权限不足](#登录失败token-错误或权限不足)
38+
- [截图](#截图)
39+
- [授权](#授权)
40+
41+
---
42+
43+
## 功能特色
44+
45+
- 🔒 为 Gin 提供简单的 JWT 认证
46+
- 🔁 内置登录、刷新、登出处理器
47+
- 🛡️ 可自定义认证、授权与 Claims
48+
- 🍪 支持 Cookie 与 Header Token
49+
- 📝 易于集成，API 清晰
50+
51+
---
52+
53+
## 安全性注意事项
54+
55+
> **警告：**
56+
> 使用弱密码（如短或简单密码）的 JWT Token 易受暴力破解攻击。
57+
> **建议：**请使用强且长的密钥或 `RS256` Token。
58+
> 详见 [jwt-cracker repository](https://github.com/lmammino/jwt-cracker)。
59+
60+
---
61+
62+
## 安装
63+
64+
### 使用 Go Modules（推荐）
65+
66+
```sh
67+
export GO111MODULE=on
68+
go get github.com/appleboy/gin-jwt/v2
69+
```
70+
71+
```go
72+
import "github.com/appleboy/gin-jwt/v2"
73+
```
74+
75+
---
76+
77+
## 快速开始示例
78+
79+
请参考 [`_example/basic/server.go`](./_example/basic/server.go) 示例文件，并可使用 `ExtractClaims` 获取 JWT 内的用户数据。
80+
81+
```go
82+
// ...（完整示例请见 _example/basic/server.go）
83+
```
84+
85+
---
86+
87+
## Demo
88+
89+
启动示例服务器：
90+
91+
```sh
92+
go run _example/basic/server.go
93+
```
94+
95+
建议安装 [httpie](https://github.com/jkbrzt/httpie) 进行 API 测试。
96+
97+
### 登录
98+
99+
```sh
100+
http -v --json POST localhost:8000/login username=admin password=admin
101+
```
102+
103+
![登录截图](screenshot/login.png)
104+
105+
### 刷新 Token
106+
107+
```sh
108+
http -v -f GET localhost:8000/auth/refresh_token "Authorization:Bearer xxxxxxxxx" "Content-Type: application/json"
109+
```
110+
111+
![刷新截图](screenshot/refresh_token.png)
112+
113+
### Hello World
114+
115+
以 `admin`/`admin` 登录后调用：
116+
117+
```sh
118+
http -f GET localhost:8000/auth/hello "Authorization:Bearer xxxxxxxxx" "Content-Type: application/json"
119+
```
120+
121+
**响应：**
122+
123+
```json
124+
{
125+
"text": "Hello World.",
126+
"userID": "admin"
127+
}
128+
```
129+
130+
### 授权示例
131+
132+
以 `test`/`test` 登录后调用：
133+
134+
```sh
135+
http -f GET localhost:8000/auth/hello "Authorization:Bearer xxxxxxxxx" "Content-Type: application/json"
136+
```
137+
138+
**响应：**
139+
140+
```json
141+
{
142+
"code": 403,
143+
"message": "You don't have permission to access."
144+
}
145+
```
146+
147+
---
148+
149+
## Cookie Token
150+
151+
如需将 JWT 设置于 Cookie，请使用以下选项（参考 [MDN 文档](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies)）：
152+
153+
```go
154+
SendCookie: true,
155+
SecureCookie: false, // 非 HTTPS 开发环境
156+
CookieHTTPOnly: true, // JS 无法修改
157+
CookieDomain: "localhost:8080",
158+
CookieName: "token", // 默认 jwt
159+
TokenLookup: "cookie:token",
160+
CookieSameSite: http.SameSiteDefaultMode, // SameSiteDefaultMode, SameSiteLaxMode, SameSiteStrictMode, SameSiteNoneMode
161+
```
162+
163+
---
164+
165+
### 登录流程（LoginHandler）
166+
167+
- **内置：** `LoginHandler`
168+
在登录端点调用此函数以触发登录流程。
169+
170+
- **必须：** `Authenticator`
171+
验证 Gin context 内的用户凭证。验证成功后返回要嵌入 JWT Token 的用户数据（如账号、角色等）。失败则调用 `Unauthorized`。
172+
173+
- **可选：** `PayloadFunc`
174+
将认证通过的用户数据转为 `MapClaims`（map[string]interface{}），必须包含 `IdentityKey`（默认 `"identity"`）。
175+
176+
- **可选：** `LoginResponse`
177+
处理登录后逻辑，例如返回 Token JSON。
178+
179+
---
180+
181+
### 需要 JWT Token 的端点（MiddlewareFunc）
182+
183+
- **内置：** `MiddlewareFunc`
184+
用于需要 JWT 认证的端点。会：
185+
186+
- 从 header/cookie/query 解析 Token
187+
- 验证 Token
188+
- 调用 `IdentityHandler` 与 `Authorizator`
189+
- 验证失败则调用 `Unauthorized`
190+
191+
- **可选：** `IdentityHandler`
192+
从 JWT Claims 获取用户身份。
193+
194+
- **可选：** `Authorizator`
195+
检查用户是否有权限访问该端点。
196+
197+
---
198+
199+
### 登出流程（LogoutHandler）
200+
201+
- **内置：** `LogoutHandler`
202+
用于登出端点。会清除 Cookie（若 `SendCookie` 设置为 true）并调用 `LogoutResponse`。
203+
204+
- **可选：** `LogoutResponse`
205+
返回登出结果的 HTTP 状态码。
206+
207+
---
208+
209+
### 刷新流程（RefreshHandler）
210+
211+
- **内置：** `RefreshHandler`
212+
用于刷新 Token 端点。若 Token 在 `MaxRefreshTime` 内，会发新 Token 并调用 `RefreshResponse`。
213+
214+
- **可选：** `RefreshResponse`
215+
返回新 Token 的 JSON。
216+
217+
---
218+
219+
### 登录失败、Token 错误或权限不足
220+
221+
- **可选：** `Unauthorized`
222+
处理登录、授权或 Token 错误时的响应。返回 HTTP 错误码与消息的 JSON。
223+
224+
---
225+
226+
## 截图
227+
228+
| 登录 | 刷新 Token |
229+
| --------------------------------- | ----------------------------------------- |
230+
| ![登录截图](screenshot/login.png) | ![刷新截图](screenshot/refresh_token.png) |
231+
232+
---
233+
234+
## 授权
235+
236+
详见 [`LICENSE`](LICENSE)。

0 commit comments

Comments
 (0)