网站源模板,营销网络建设体系,成都网站建站推广,wordpress 错位一文搞懂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);
GraphQL与数据库查询的区别
GraphQL客户端自定义返回字段如 { user { id, name } }返回 JSON 格式数据。ORM如 Hibernate 将数据库表映射为 Java 对象执行固定查询。定位GraphQL 位于 API 层替代 RESTORM 位于持久层数据库操作。
GraphQL兼容性既可以用 Spring BootJava 也可以用 Flask/FastAPIPython 实现。它是一个独立的 API 查询语言。
RestController
public class GraphQLController {PostMapping(/graphql)public String executeGraphQL(RequestBody String query) {return GraphQL Response;}
}import grapheneclass Query(graphene.ObjectType):hello graphene.String()def resolve_hello(root, info):return Hello, World!schema graphene.Schema(queryQuery)FastAPI兼容异步库如 asyncpg不兼容同步阻塞代码。Flask兼容传统同步库如 SQLAlchemy。Spring Boot兼容主流数据库MySQL、PostgreSQL和 ORMJPA/Hibernate。GraphQL可与任何后端语言和数据库配合使用。
