一文搞懂RESTful API - bigsai - 博客园

1. API 路径   开头必须 /，表示绝对路径，不支持 . 或 ..（相对路径）。API 结尾 / 通常不需要，但部分框架会自动处理 / → 无 /。

✅ 推荐

GET /api/v1/products    # 资源集合
GET /api/v1/products/123  # 具体资源

🚫 避免

GET ./api/v1/products    # ❌ API 不能用 `.` 开头
GET /api/v1/products/    # ❌ 可能导致 404

2. 系统路径  Linux/Windows 支持 . 开头（相对路径）。结尾 / 代表目录，不加 / 可能是文件。

/home/user/docs/    # 目录
/home/user/docs.txt # 文件

3. 关键区别

特性	API 路径	系统路径
相对路径	❌ 不支持 .	✅ ./file.txt 代表当前目录
绝对路径	✅ /api/v1/users	✅ /home/user/docs/
结尾 /	🚫 通常不加	✅ 代表目录

✅ 最佳实践  API 必须 / 开头，通常不加结尾 /。文件路径 目录加 /，文件不加 /。

---

Swagger 提供了一套完整的工具集，用于设计、构建、文档化和测试 RESTful API。其核心组件包括 Swagger Codegen 和 Swagger UI。Swagger Codegen 生成的是代码框架（客户端 SDK 或服务端模板），需要开发者补充逻辑才能运行。Swagger UI 生成的是交互式文档网页，用于展示和测试 API，不涉及代码生成。

1. Swagger Codegen 的作用与效果

功能：根据 OpenAPI 规范（YAML/JSON 格式的 API 描述文件），自动生成客户端 SDK（如 Java、Python 的调用库）和服务器端框架代码（如 Spring Boot、Flask 的接口实现模板）。

生成内容：

• 代码文件：例如生成 Java 的模型类、接口定义、HTTP 请求工具类，或 Python 的 Flask 路由代码等。这些文件需要开发者进一步补充业务逻辑才能运行。
• 支持框架：生成的代码适配多种框架（如 Spring Boot、Django、Express），但并非“完整的应用程序”，而是提供基础代码框架，开发者需自行完善。

使用场景：假设你有一个 OpenAPI 文件，通过 Swagger Codegen 可以快速生成客户端调用库（供其他服务使用你的 API）或服务端接口模板（简化开发流程）。

---

2. Swagger UI 的作用与效果

功能：将 OpenAPI 规范文件转换为交互式文档网页，允许用户直接在浏览器中查看 API 端点、参数说明，并实时发送请求测试接口。

生成内容：

• 可视化界面：以 HTML/CSS/JS 渲染的网页，展示 API 的路径、请求方法、参数、响应示例等。用户可填写参数并点击“Try it out”测试接口。

• 实时反馈：显示请求的响应结果（如 JSON 数据）、状态码及错误信息，帮助开发者和测试人员快速验证 API 功能。

使用场景：在开发阶段，后端团队通过 Swagger UI 提供文档给前端或测试团队，减少沟通成本；部署后，作为 API 的官方文档供外部调用者参考。

---

3. OpenAPI 规范文件的实际形态

文件格式：通常是 YAML 或 JSON 文件，例如 openapi.yaml 或 swagger.json，定义了 API 的元数据（如标题、版本）、端点路径、请求方法、参数类型、响应格式及错误码等。例如：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户列表

Swagger UI 的界面示例
访问方式：启动服务后，通过 URL（如 http://localhost:8080/swagger-ui.html）打开页面。

界面元素：API 列表：左侧展示所有接口路径（如 /users、/orders）。参数输入框：支持填写路径参数、查询参数、请求体（JSON 格式）。测试按钮：点击“Try it out”发送请求，页面下方显示服务器响应结果。示例值：自动生成请求和响应的示例数据，帮助理解接口用法。

---

4. RESTful API 框架分类

Java 生态：Spring Boot：最流行的 Java 框架，内置 Tomcat，支持快速构建 REST API。JAX-RS：Java 标准（如 Jersey、RESTEasy），基于注解开发。

Python 生态：Django REST Framework：基于 Django，适合复杂业务和权限控制。Flask：轻量级，通过扩展（如 Flask-RESTful）支持 REST。FastAPI：高性能，支持异步和自动生成 Swagger 文档。

5. 跨语言项目的可行性

可以同时使用 Java 和 Python 框架，但需要通过 API 通信或消息队列解耦。例如：Java 主系统：处理核心业务（如医院管理系统的患者数据）Python 子服务：调用 LLM（如 GPT-3）生成 SQL，通过 HTTP API 返回结果给 Java 系统。

技术实现：Java 后端调用 Python 服务的 API（如 FastAPI 暴露的 /generate-sql 端点）。数据格式统一（如 JSON），确保跨语言解析兼容。使用 API 网关（如 Spring Cloud Gateway）统一管理请求路由。

---

 FastAPI、Postman、Flask 的关系 

• FastAPI 和 Flask：两者都是 Python 的 Web 框架，用于构建 API。FastAPI 的性能优于 Flask，适合大规模并发应用。Flask 适合简单的 Web 应用。
  • FastAPI：基于 ASGI（异步服务器网关接口），支持异步编程和高性能，内置数据验证（Pydantic）、自动文档生成（Swagger/ReDoc）。Flask：基于 WSGI（同步接口），轻量级但需手动处理数据验证和文档生成。
  • 兼容性：FastAPI 与异步数据库（如 asyncpg）更适配，Flask 适合搭配传统同步库（如 SQLAlchemy）。
  • Postman：独立于框架的 API 测试工具，用于调试和验证 FastAPI/Flask 开发的接口。

示例代码（FastAPI vs Flask）

# FastAPI 示例（异步）
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

# 运行: uvicorn filename:app --reload

# Flask 示例（同步）
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/items/<int:item_id>', methods=['GET'])
def get_item(item_id):
    return jsonify({"item_id": item_id})

# 运行: python filename.py
if __name__ == '__main__':
    app.run(debug=True)

RESTful API 里没有方法定义，我如何判断它是增删改查？

RESTful API 通过 HTTP 方法 来区分操作，而不是通过 URL。例如：

方法	作用	示例 URL
GET	获取数据	GET /users/1
POST	创建数据	POST /users
PUT	更新数据	PUT /users/1
DELETE	删除数据	DELETE /users/1

如果 URL 里没有明确的增删改查，通常需要看 HTTP 方法（GET、POST、PUT、DELETE）来判断它的作用。

API 是不是就等于链接？

不完全正确。API（应用程序接口）可以包含但不等同于 URL，API 指的是一组规则和协议，不仅限于 HTTP，还可以是数据库 API、操作系统 API、函数库 API 等。API ≠ 网址，但 Web API 确实会以 URL 的形式暴露出来。

Web API：
GET https://api.example.com/users/1

数据库 API（Java 代码）：
Connection conn = DriverManager.getConnection("jdbc:mysql://localhost:3306/mydb", "user", "password");

操作系统 API（调用 Windows API）：
#include <windows.h>
MessageBox(0, "Hello", "Message Box", MB_OK);

GraphQL与数据库查询的区别：

• GraphQL：客户端自定义返回字段（如 { user { id, name } }），返回 JSON 格式数据。ORM（如 Hibernate） ：将数据库表映射为 Java 对象，执行固定查询。
• 定位：GraphQL 位于 API 层（替代 REST），ORM 位于持久层（数据库操作）。

GraphQL兼容性：既可以用 Spring Boot（Java） 也可以用 Flask/FastAPI（Python） 实现。它是一个独立的 API 查询语言。

@RestController
public class GraphQLController {
    @PostMapping("/graphql")
    public String executeGraphQL(@RequestBody String query) {
        return "GraphQL Response";
    }
}

import graphene

class Query(graphene.ObjectType):
    hello = graphene.String()

    def resolve_hello(root, info):
        return "Hello, World!"

schema = graphene.Schema(query=Query)

• FastAPI：兼容异步库（如 asyncpg），不兼容同步阻塞代码。
• Flask：兼容传统同步库（如 SQLAlchemy）。
• Spring Boot：兼容主流数据库（MySQL、PostgreSQL）和 ORM（JPA/Hibernate）。
• GraphQL：可与任何后端语言和数据库配合使用。