当前位置: 首页 > article >正文

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.yamlswagger.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:可与任何后端语言和数据库配合使用。


http://www.kler.cn/a/547726.html

相关文章:

  • 科普:“表格式 ”与“ 存储格式”
  • 【环境配置】Ubuntu 22.04 C++ header file not found using Vim with YouCompleteMe
  • Redis 设置密码无效问题解决
  • c++--变量内存分配
  • 【开源项目】Excalidraw手绘风格白板(保姆级)教程
  • 如何学BI大数据
  • Html、Markdown的信息提取
  • LabVIEW 中 dotnet.llb 库功能
  • 05-服务保护和分布式事务(Sentinel、Seata)
  • Linux文件管理:硬链接与软链接
  • 图论 - 一些经典小算法思想(无题目例子)
  • 《open3d qt 网格泊松采样成点云》
  • 关于Dest1ny:我的创作纪念日
  • JavaScript原型和原型链
  • 代码随想录二刷|动态规划3
  • 鸿蒙Harmony-应用状态-AppStorage详细介绍
  • 蓝桥杯---排序数组(leetcode第912题)
  • 神经网络常见激活函数 12-Swish函数
  • 游戏引擎学习第104天
  • Nacos 详细介绍:微服务架构中的服务发现与配置管理利器