Skip to main content

mockpath

PyPI

轻量级 HTTP Mock 服务器。通过 YAML 配置 + JSON 文件定义模拟接口,目录结构即 URL 路径。

特性

  • 目录结构自动映射为 URL 路径
  • YAML 定义接口配置,JSON 定义请求/响应体
  • 支持 query 参数匹配(子集匹配,请求中的额外参数不影响匹配)
  • 支持请求体匹配(深度相等比较)
  • 请求体和响应体均支持内联、文件引用、约定命名三种方式
  • --reload 模式自动监听文件变更并热重载
  • 未知路径返回 404,方法不匹配返回 405

安装

pip install mockpath

或使用 uv:

uv tool install mockpath

使用

mockpath [-p PORT] [-d DIR] [--reload]
参数 说明 默认值
-p, --port 监听端口 8000
-d, --dir 配置目录 ./api
--reload 监听文件变更,自动重载配置 关闭
--version 显示版本号
--help 显示帮助信息

文件命名规则

api/                              # 配置根目录(通过 -d 指定)
  v1/
    users/
      list.get.yaml               # GET /v1/users/list 的配置
      list.get.resp.json           # 默认响应
      list.get.resp.1.json         # 匹配规则 #1 的响应
      profile.post.yaml            # POST /v1/users/profile 的配置
      profile.post.resp.json       # 默认响应
      profile.post.req.1.json      # 匹配规则 #1 的请求体
      profile.post.resp.1.json     # 匹配规则 #1 的响应

命名模式:<端点名>.<HTTP方法>.yaml

YAML 配置格式

基础接口(无匹配规则)

# profile.get.yaml
status: 200

响应体来自 profile.get.resp.json。

Query 参数匹配

# list.get.yaml
status: 200
matches:
  - params:
      page: "1"
      limit: "10"
  - params:
      page: "2"
    response:               # 内联响应
      users: []
      total: 0

匹配逻辑:请求的 query 参数是配置参数的超集即可匹配(子集匹配)。

请求体匹配(POST/PUT/PATCH)

# profile.post.yaml
status: 201
matches:
  - request:                 # 内联请求体
      name: "Bob"
    response_file: resp.1.json
  - request_file: req.2.json # 引用外部请求体文件
    response:
      id: 4
      name: "Alice"
  - status: 200              # 约定命名:请求体来自 profile.post.req.3.json

请求体的三种指定方式

每条匹配规则的请求体按以下优先级确定:

  1. request — YAML 中的内联 JSON 请求体
  2. request_file — 引用外部文件(相对于 YAML 文件的路径)
  3. 约定命名 — 自动查找 <端点名>.<方法>.req.N.json

响应的三种指定方式

每条匹配规则的响应按以下优先级确定:

  1. response — YAML 中的内联 JSON 响应
  2. response_file — 引用外部文件(相对于 YAML 文件的路径)
  3. 约定命名 — 自动查找 <端点名>.<方法>.resp.N.json

匹配流程

  1. 按 matches 列表顺序逐一尝试
  2. 第一个匹配成功的规则生效(first match wins)
  3. 无匹配 → 返回默认响应

示例

# 启动服务器
mockpath -p 3000

# Query 参数匹配
curl "http://localhost:3000/v1/users/list?page=1"
# → [{"id": 1, "name": "Alice"}]

curl "http://localhost:3000/v1/users/list?page=2"
# → {"users": [], "total": 0}

# 请求体匹配
curl -X POST http://localhost:3000/v1/users/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "Bob"}'
# → {"id": 3, "name": "Bob"}

# 无匹配时返回默认响应
curl "http://localhost:3000/v1/users/list"
# → [{"id": 1, "name": "Alice"}]

依赖

Metadata

Release files for mockpath 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mockpath 0.1.2
File Size Uploaded Provenance Actions
mockpath-0.1.2.tar.gz 12.3 kB Without provenance Details for mockpath-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mockpath 0.1.2
File Interpreter ABI Platform Actions
mockpath-0.1.2-py3-none-any.whl Python 3 none any Details for mockpath-0.1.2-py3-none-any.whl

Total release size: 18.0 kB

Release files / mockpath-0.1.2.tar.gz

Download URL mockpath-0.1.2.tar.gz
Size 12.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bcd07cec7f0893b7ddd2e9881d76c9f6ed5cebc2d6144276b60fb4df04658371
BLAKE2b-256 checksum
How to use checksums
df72fdf902e4936227b5214773ca552c977e3df5ec90644b3c81183b25179ef7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.17

Release files / mockpath-0.1.2-py3-none-any.whl

Download URL mockpath-0.1.2-py3-none-any.whl
Size 5.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5a881e7e20b1fb34a9f631084b4dc1b34483706293c96a37b24bfe5439b75ce6
BLAKE2b-256 checksum
How to use checksums
2b4b77a8c7022a08bd4e49476e7cfa940a80e63aa3c446e798f536a76c2164f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.17

Security for mockpath 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page