深圳网站备案注销,wordpress文章列表 框,长沙网站搭建seo,哈尔滨云建站模板一文搞懂RESTful API - bigsai - 博客园 1. API 路径 开头必须 /#xff0c;表示绝对路径#xff0c;不支持 . 或 ..#xff08;相对路径#xff09;。API 结尾 / 通常不需要#xff0c;但部分框架会自动处理 / → 无 /。
✅ 推荐
GET /api/v1/products # 资源集合…
一文搞懂RESTful API - bigsai - 博客园 1. API 路径 开头必须 /表示绝对路径不支持 . 或 ..相对路径。API 结尾 / 通常不需要但部分框架会自动处理 / → 无 /。
✅ 推荐
GET /api/v1/products # 资源集合
GET /api/v1/products/123 # 具体资源避免
GET ./api/v1/products # ❌ API 不能用 . 开头
GET /api/v1/products/ # ❌ 可能导致 4042. 系统路径 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: 示例APIversion: 1.0.0
paths:/users:get:summary: 获取用户列表parameters:- name: limitin: queryschema:type: integerresponses: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-RSJava 标准如 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 FastAPIapp 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, jsonifyapp 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(debugTrue)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应用程序接口可以包含但不等同于 URLAPI 指的是一组规则和协议不仅限于 HTTP还可以是数据库 API、操作系统 API、函数库 API 等。API ≠ 网址但 Web API 确实会以 URL 的形式暴露出来。
Web API
GET https://api.example.com/users/1数据库 APIJava 代码
Connection conn DriverManager.getConnection(jdbc:mysql://localhost:3306/mydb, user, password);操作系统 API调用 Windows API
#include windows.h
MessageBox(0, Hello, Message Box, MB_OK); #### 应用层是客户端和服务器端都有的
1. 应用层的定义
应用层是网络体系结构中的最高层直接面向用户和应用程序它负责处理高层协议常见的应用层协议包括HTTP、FTP、SMTP、DNS等。客户端和服务器端的应用层职责和运行环境不同。客户端应用层主要处理用户输入和界面呈现而服务器端应用层主要处理业务逻辑和数据存储。两者通过网络协议如HTTP进行通信 客户端应用层 运行在用户设备上的应用程序或进程如Web浏览器、电子邮件客户端等。发送请求并处理响应。例如用户在浏览器中输入网址浏览器作为客户端应用层会向目标Web服务器发送HTTP请求获取网页内容并呈现给用户。 服务器端应用层 运行在服务器上的应用程序或服务如Web服务器、邮件服务器等。接收并处理来自客户端的请求返回相应的数据或服务。例如Web服务器接收到浏览器的HTTP请求后会处理该请求并返回相应的网页内容。
3. 应用层在客户端和服务器端的交互示例
以下是一个简单的HTTP请求-响应过程 客户端浏览器发送HTTP请求 GET /index.html HTTP/1.1
Host: www.example.com服务器Web服务器接收请求并返回响应 HTTP/1.1 200 OK
Content-Type: text/htmlhtml
headtitleExample Page/title/head
bodyh1Welcome to Example.com!/h1
/body
/html**前端框架主要是针对于客户端而言的概念**
前端框架如React、Vue是用于构建用户界面的JavaScript框架运行在客户端浏览器中。这些框架帮助开发者创建动态、交互式的网页应用。虽然服务器端也可以使用类似的框架如Next.js、Nuxt.js进行服务端渲染但传统意义上的前端框架主要存在于客户端用于处理用户界面和交互。
#### 缓存
缓存机制在应用层而应用层是客户端和服务器端都有的 客户端缓存客户端应用程序可以在本地存储数据以减少对服务器的请求次数提高响应速度。例如浏览器会缓存静态资源如HTML、CSS、JavaScript文件以加快页面加载速度。 服务器端缓存服务器可以在内存中存储经常访问的数据或计算结果以减少对底层数据库的访问提高处理效率。例如使用内存对象缓存如Memcached数据库缓存使用 Redis来存储热点数据。
1. 浏览器缓存HTTP 缓存
示例使用 Cache-Control 和 ETag 实现缓存控制 服务器端Node.js 示例
const http require(http);
const crypto require(crypto);// 模拟的资源数据
const resourceData Hello, this is the resource content.;// 计算资源的 ETag可以使用资源内容的哈希值
const etag crypto.createHash(md5).update(resourceData).digest(hex);const server http.createServer((req, res) {if (req.url /resource) {const ifNoneMatch req.headers[if-none-match];// 检查请求头中的 If-None-Match 是否与服务器的 ETag 匹配if (ifNoneMatch etag) {// ETag 匹配资源未修改返回 304 Not Modifiedres.writeHead(304, {Cache-Control: public, max-age3600, // 缓存时间为 1 小时ETag: etag,});res.end();} else {// ETag 不匹配资源已修改返回新的资源和 ETagres.writeHead(200, {Content-Type: text/plain,Cache-Control: public, max-age3600,ETag: etag,});res.end(resourceData);}} else {res.writeHead(404, { Content-Type: text/plain });res.end(Not Found);}
});server.listen(3000, () {console.log(Server running at http://localhost:3000/);
});客户端浏览器请求
// 使用 Fetch API 请求资源
fetch(http://localhost:3000/resource).then((response) {if (response.status 200) {// 资源已更新处理新的资源内容return response.text().then((data) {console.log(Resource data:, data);});} else if (response.status 304) {// 资源未修改使用缓存中的数据console.log(Resource not modified. Using cached version.);}}).catch((error) {console.error(Error fetching resource:, error);});流程图解 首次请求客户端请求 http://localhost:3000/resource。服务器返回资源内容状态码 200并包含 Cache-Control 和 ETag 头。 HTTP/1.1 200 OK
Content-Type: text/plain
Cache-Control: public, max-age3600
ETag: 5d41402abc4b2a76b9719d911017c592Hello, this is the resource content.后续请求在缓存有效期内客户端再次请求相同资源并在请求头中包含 If-None-Match。服务器检查 If-None-Match发现资源未修改返回 304 状态码无需传输资源内容。客户端接收到 304 响应后从缓存中读取并使用资源内容。 GET /resource HTTP/1.1
Host: localhost:3000
If-None-Match: 5d41402abc4b2a76b9719d911017c592HTTP/1.1 304 Not Modified
Cache-Control: public, max-age3600
ETag: 5d41402abc4b2a76b9719d911017c5922. 应用层缓存示例在 React 应用中使用 localStorage 缓存 API 响应数据
步骤 首次加载应用时检查 localStorage 中是否存在缓存的新闻数据。如果存在且未过期直接使用缓存的数据渲染界面。如果不存在或已过期发送网络请求获取最新数据渲染界面并将数据缓存到 localStorage。 在组件中实现 import React, { useEffect, useState } from react;const NewsComponent () {const [news, setNews] useState([]);const cacheKey newsData;const cacheExpiry 60 * 60 * 1000; // 缓存有效期1 小时useEffect(() {const fetchNews async () {try {const cachedData localStorage.getItem(cacheKey);if (cachedData) {const { data, timestamp } JSON.parse(cachedData);if (Date.now() - timestamp cacheExpiry) {// 使用缓存的数据setNews(data);console.log(Using cached data);return;}}// 缓存不存在或已过期发送网络请求const response await fetch(https://api.example.com/news);const data await response.json();setNews(data);// 将新数据缓存到 localStoragelocalStorage.setItem(cacheKey,JSON.stringify({ data, timestamp: Date.now() }));console.log(Fetched and cached new data);} catch (error) {console.error(Error fetching news:, error);}};fetchNews();}, []);return (divh1Latest News/h1ul{news.map((item) (li key{item.id}{item.title}/li))}/ul/div);
};export default NewsComponent;RESTful API 是改变服务器的资源还是改变客户端的资源
RESTful API 主要是用来操作服务器端的资源而客户端的状态是如何随之变化的取决于客户端如何使用 API 提供的数据。 服务器端资源的改变通过 POST 创建新资源等等只有 GET 不会修改服务器端数 客户端状态是指客户端的 UI、页面展示、数据缓存等。RESTful API 并不会直接管理客户端的状态而是提供数据让客户端自己决定如何更新其状态。例如用户请求 GET /users/1服务器返回用户数据客户端用这个数据来更新页面但服务器上的数据没有变
REST 设计的无状态性Stateless是指服务器不会存储客户端的会话状态每个请求都是独立的不依赖之前的请求。客户端必须在每个请求中提供所有必要的信息例如身份认证Token、Session ID 等。服务器根据请求中的信息做出响应而不会记住上一次请求的状态。 传统 Web 应用有状态用户登录后服务器会在内存里保存用户会话后续请求只需要提供一个 session_id。 RESTful API无状态每次请求都必须带上 Authorization 头服务器不会记住用户的身份而是根据请求中的 Token 进行验证。 #### 筛选和分页
标准的 URL 查询参数不直接支持 OR 操作。需要看API服务器提供端究竟是怎么规定的。一种常见的解决方案是使用逗号分隔的列表表示多个值。
GET /classes?namedef,ABC或者重复参数
GET /classes?namedefnameABC分页查询通常通过在 URL 中添加 page 和 size 参数来实现分别表示页码和每页的数据量。
GET /classes?page1size10此请求表示获取第 1 页的数据每页包含 10 条记录。如果有多页数据可以调整 page 参数的值来获取不同页的数据。
GET /classes?page2size10此请求表示获取第 2 页的数据每页同样包含 10 条记录。
某些 API 中可能使用 offset 和 limit 参数来控制分页此请求表示从第 11 条记录开始获取 10 条记录。
GET /classes?offset10limit10
