HTML,API,RestFul API基础
一文搞懂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 | 获取数据 |
|
POST | 创建数据 |
|
PUT | 更新数据 |
|
DELETE | 删除数据 |
|
如果 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:可与任何后端语言和数据库配合使用。