HTTP Method Laboratory

多语言 HTTP 方法学习实验室（HTTP Method Lab）。

同一套 REST / 协议语义，用 Python · Node.js · TypeScript · Go · Rust · Java (MVC / WebFlux) · Kotlin (Ktor / Spring MVC) 各实现一份，方便对照学习：

• 方法：GET / HEAD / POST / PUT / PATCH / DELETE / OPTIONS
• 变体：JSON / form / multipart / JSON Patch、ETag / 304、幂等键、upsert、If-Match、软删 / 204、CORS 预检教学、状态码橱窗等
• 响应：统一 JSON 外壳 success · code · message · data · lesson · meta
• 日志：控制台 [lab] --> / [lab] <-- + 状态码教学 tip
• 文档：每个子项目自带独立 README（不互相依赖）

用途：本地学习与对照实验。不是生产级脚手架（无真实 DB / 鉴权产品 / 完整 CORS 中间件）。

---

仓库结构

.
├── README.md                 # 本文件（总览）
├── CONTRIBUTING.md           # 贡献说明
├── COMMENTING.md             # 中英注释与日志约定
├── .gitignore
├── .editorconfig
├── docs/                     # 设计笔记（可选阅读）
├── flask-http-demo/          # Python + Flask              :5000
├── nodejs-http-demo/         # Node.js + Express           :5001
├── typescript-http-demo/     # TypeScript + Express        :5002
├── go-http-demo/             # Go + net/http               :5003
├── rust-http-demo/           # Rust + Axum                 :5004
├── java-spring-mvc-demo/     # Java + Spring MVC + Maven     :5005
├── java-webflux-demo/        # Java + WebFlux + Gradle 8     :5006
├── kotlin-ktor-demo/         # Kotlin + Ktor + Gradle        :5007
└── kotlin-spring-mvc-demo/   # Kotlin + Spring MVC + Gradle  :5008

目录	技术栈	默认端口	启动	测试
flask-http-demo	Python 3 · Flask	5000	python run.py	pytest -q
nodejs-http-demo	Node ≥20 · Express	5001	npm start	npm test
typescript-http-demo	TypeScript · Express · tsx	5002	npm run dev	npm test
go-http-demo	Go 1.22+ · stdlib	5003	go run ./cmd/server	go test ./...
rust-http-demo	Rust · Axum · Tokio	5004	cargo run --bin server	cargo test
java-spring-mvc-demo	Java 17 · Spring MVC · Maven	5005	mvn spring-boot:run	mvn test
java-webflux-demo	Java 17 · WebFlux · Gradle 8	5006	./gradlew bootRun	./gradlew test
kotlin-ktor-demo	Kotlin · Ktor · coroutines	5007	./gradlew run	./gradlew test
kotlin-spring-mvc-demo	Kotlin · Spring MVC · Gradle	5008	./gradlew bootRun	./gradlew test

每个子目录的 README 是完整教材（接口表、curl、响应结构、FAQ）。

---

快速体验（任选其一）

Flask

cd flask-http-demo
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py
# http://127.0.0.1:5000

Node.js

cd nodejs-http-demo
npm install && npm start
# http://127.0.0.1:5001

TypeScript

cd typescript-http-demo
npm install && npm run dev
# http://127.0.0.1:5002

Go

cd go-http-demo
go run ./cmd/server
# http://127.0.0.1:5003

Rust

# 需本机已安装 rustup / cargo
cd rust-http-demo
cargo run --bin server
# http://127.0.0.1:5004

Java · Spring MVC (Maven)

# 需 JDK 17+ 与 Maven
cd java-spring-mvc-demo
mvn spring-boot:run
# http://127.0.0.1:5005

Java · Spring WebFlux (Gradle 8)

# 需 JDK 17+；推荐使用仓库自带 Gradle Wrapper
cd java-webflux-demo
./gradlew bootRun
# http://127.0.0.1:5006

Kotlin · Ktor

cd kotlin-ktor-demo
./gradlew run
# http://127.0.0.1:5007

Kotlin · Spring MVC

cd kotlin-spring-mvc-demo
./gradlew bootRun
# http://127.0.0.1:5008

统一探测

# 将 PORT 换成对应端口
curl -s http://127.0.0.1:5001/api/v1 | head
curl -si http://127.0.0.1:5001/api/v1/items/json \
  -H 'Content-Type: application/json' \
  -d '{"name":"Hello","price":1}'

控制台会看到类似：

[lab] --> POST /api/v1/items/json  Content-Type=application/json  ...
[lab] <-- POST /api/v1/items/json  201  3.2ms  Location=/api/v1/items/1 ...
[lab] tip: 201 Created — resource created; check Location header.
[lab] ---

---

共享约定（跨语言）

JSON 成功外壳

{
  "success": true,
  "code": 201,
  "message": "created",
  "data": { },
  "lesson": {
    "method": "POST",
    "variant": "application/json create",
    "semantics": "..."
  },
  "meta": {
    "method": "POST",
    "path": "/api/v1/items/json",
    "content_type": "application/json"
  }
}

主要路径族

族	示例
元信息	GET /health · GET /api/v1
资源	/api/v1/items · /api/v1/items/{id} · /json · /form · /multipart · /json-patch
Demo	/api/v1/demo/get/* · post/* · put/* · delete/* · options/* · status/{code}

同一套 curl 只改 BASE 端口 即可对照多语言实现。

复杂度直觉（教学向）

维度	更简单 / 更快写出	更高运行效率
心智 / 脚手架	Flask · Node	—
类型协作	TypeScript · Go · Java	—
企业 Java 栈	Spring MVC (Maven)	—
响应式 Java	Spring WebFlux (Gradle)	事件循环（Netty）
Kotlin 原生服务端	Ktor + 协程	—
Kotlin + 企业栈	Spring MVC (Kotlin DSL)	—
运行时性能 / 部署	—	Go · Rust

详见各子项目 README。

---

推荐学习路径

1. 读本 README，跑通 任意一门 的 /health 与 /api/v1
2. 用 curl 走完「创建 → 列表 → ETag → PATCH → 删除」
3. 对照控制台 [lab] 日志 看状态码 tip
4. 读该语言的 store / parsing / responses 源码
5. 换另一门语言，对比同样路径的实现差异

注释约定见 COMMENTING.md。

---

推送到 GitHub（建议步骤）

仓库根目录当前尚未强制附带 .git 历史。你可在本机：

cd /path/to/this/repo
git init
git add .
git status   # 确认没有 node_modules / .venv / target / uploads 内容
git commit -m "Initial commit: multi-language HTTP method laboratory"

# 在 GitHub 新建空仓库（不要勾选自动添加 README，或先拉再合并）
# 创建时可选 License（本仓库不内置 LICENSE 文件，由 GitHub 界面生成）

git remote add origin git@github.com:<you>/<repo>.git
git branch -M main
git push -u origin main

请勿提交：

• node_modules/、.venv/、target/、build/、dist/、.gradle/
• uploads/ 下的用户文件（仅保留 .gitkeep）
• .env 等密钥

根目录 .gitignore 已覆盖常见生成物。

---

贡献

见 CONTRIBUTING.md。

---

安全提示

• 默认监听 0.0.0.0 便于局域网调试；公网暴露前请改为本机绑定并加鉴权。
• 内存存储与教学 lesson 字段不适合生产。
• Debug / 详细 500 信息仅限本地学习。

---

许可

本仓库不包含 LICENSE 文件。发布到 GitHub 时请在创建仓库界面选择 License（或稍后在 Settings → License 添加）。