Hyperswitch项目本地环境搭建与API测试指南

顾能培Wynne

于 2025-06-01 09:16:51 发布

阅读量421

点赞数 3

本文链接：https://blog.csdn.net/gitblog_00930/article/details/148362736

版权

Hyperswitch项目本地环境搭建与API测试指南

hyperswitch juspay/hyperswitch: 这是一个用于实现API网关和微服务的Java库。适合用于需要实现API网关和微服务的场景。特点：易于使用，支持多种API网关和微服务实现，具有高性能和可扩展性。项目地址: https://gitcode.com/gh_mirrors/hy/hyperswitch

前言

Hyperswitch是一个开源的支付路由系统，本文将为开发者详细介绍如何在本地环境中搭建Hyperswitch项目并进行API测试。无论你是想快速体验Hyperswitch的功能，还是准备参与项目开发，本文都将提供全面的指导。

一、环境搭建方案选择

Hyperswitch提供了多种本地运行方案，开发者可根据自身需求选择：

Docker Compose方案（推荐新手使用）
- 最简单快捷的部署方式
- 适合快速体验系统功能
- 无需安装额外依赖
开发环境方案
- 适合需要修改代码的开发者
- 提供完整的开发环境
- 支持代码热更新
Nix环境方案（实验性）
- 提供可复现的开发环境
- 自动管理依赖项
- 适合高级用户
原生Rust环境方案
- 需要手动安装所有依赖
- 提供最大的灵活性
- 适合Rust开发者

二、Docker Compose快速部署

准备工作

确保系统已安装Docker Compose或Podman Compose
建议分配至少4GB内存给Docker

部署步骤

获取项目代码：

git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch
cd hyperswitch

启动服务：
```
scripts/setup.sh
```
根据提示选择配置选项：
- 基础服务：支付路由核心功能
- 附加服务：调度器和监控服务（可选）
验证服务状态：
```
curl -I http://localhost:8080/health
```
返回200状态码表示服务已就绪

三、开发环境搭建

1. 基于Docker的开发环境

docker compose -f docker-compose-development.yml up -d

注意：首次编译可能需要30分钟以上，取决于机器性能

2. Nix开发环境（实验性）

安装Nix

curl -L https://detsys.dev/nix-installer | sh

启动依赖服务

nix run .#ext-services

该命令会启动：

PostgreSQL数据库（已预配置）
Redis缓存服务

四、原生Rust环境搭建

系统依赖安装

Ubuntu/WSL2

sudo apt update
sudo apt install postgresql redis-server libpq-dev pkg-config libssl-dev

MacOS

brew install postgresql@14 redis openssl

Windows

建议使用WSL2或直接安装PostgreSQL和Redis

Rust工具链安装

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

数据库配置

创建数据库用户：

sudo -u postgres psql -c "CREATE USER hyperswitch WITH PASSWORD 'password' CREATEDB;"

创建数据库：

sudo -u postgres psql -c "CREATE DATABASE hyperswitch_db;"

运行迁移：

export DATABASE_URL=postgres://hyperswitch:password@localhost:5432/hyperswitch_db
diesel migration run

五、应用配置与启动

配置文件说明

配置文件位于config/目录：

development.toml - 开发环境配置
sandbox.toml - 沙盒环境配置
production.toml - 生产环境配置

启动应用

cargo run

或使用Nix：

nix run

六、API测试指南

1. 商户账户设置

获取管理员API密钥（位于config文件中）
配置Postman环境变量：
- baseUrl: http://localhost:8080
- admin_api_key: 你的管理员密钥

2. 创建API密钥

使用管理员密钥调用/api_keys接口创建业务API密钥

3. 支付连接器配置

选择支持的支付处理器（如Stripe、PayPal）
配置商户账户凭证

4. 支付流程测试

curl -X POST http://localhost:8080/payments \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "payment_method": "card"
  }'

5. 退款流程测试

curl -X POST http://localhost:8080/refunds \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "payment_id": "PAYMENT_ID",
    "amount": 1000
  }'