12 KiB

Raw Permalink Blame History

Spiderman - Hyperledger Fabric Asset Transfer REST API

这是一个基于Hyperledger Fabric的资产转移REST API服务，代号为Spiderman，提供了完整的RESTful接口来管理区块链上的资产。

功能特性

初始化账本
创建资产
查询所有资产
根据ID查询资产
转移资产所有权
更新资产信息
完整的Swagger API文档
交互式API测试界面

先决条件

Go 1.23.0 或更高版本
Hyperledger Fabric网络已运行
正确配置的证书和密钥文件

安装和运行

下载依赖项：

go mod tidy

启动服务：

go run .

服务默认在端口8080上运行，可以通过环境变量PORT自定义端口。

API 接口

基础URL

http://localhost:8080/api/v1

🔍 Swagger API 文档

访问地址： http://localhost:8080/swagger/index.html

Swagger提供完整的API文档和交互式测试界面，您可以：

查看所有API端点的详细信息
在线测试API接口
查看请求/响应示例
下载API规范文件（JSON/YAML）

健康检查

GET /health

1. 初始化账本

初始化区块链账本，创建初始资产集合。

POST /api/v1/ledger/init

响应示例：

{
    "success": true,
    "message": "Ledger initialized successfully"
}

2. 获取所有资产

查询账本上的所有资产。

GET /api/v1/assets

响应示例：

{
    "success": true,
    "data": [
        {
            "ID": "asset1",
            "color": "blue",
            "size": "5",
            "owner": "Tomoko",
            "appraisedValue": "1000"
        }
    ]
}

3. 创建资产

创建一个新的资产。

POST /api/v1/assets

请求体：

{
    "id": "asset123",
    "color": "red",
    "size": "10",
    "owner": "Alice",
    "appraisedValue": "2000"
}

响应示例：

{
    "success": true,
    "message": "Asset created successfully",
    "data": {
        "ID": "asset123",
        "color": "red",
        "size": "10",
        "owner": "Alice",
        "appraisedValue": "2000"
    }
}

4. 根据ID查询资产

根据资产ID查询特定资产。

GET /api/v1/assets/{id}

响应示例：

{
    "success": true,
    "data": {
        "ID": "asset123",
        "color": "red",
        "size": "10",
        "owner": "Alice",
        "appraisedValue": "2000"
    }
}

5. 转移资产所有权

转移资产的所有权给新的拥有者。

PUT /api/v1/assets/{id}/transfer

请求体：

{
    "newOwner": "Bob"
}

响应示例：

{
    "success": true,
    "message": "Asset asset123 transferred to Bob successfully"
}

6. 更新资产

更新现有资产的信息。

PUT /api/v1/assets/{id}

请求体：

{
    "color": "green",
    "size": "15",
    "owner": "Charlie",
    "appraisedValue": "3000"
}

响应示例：

{
    "success": true,
    "message": "Asset updated successfully",
    "data": {
        "ID": "asset123",
        "color": "green",
        "size": "15",
        "owner": "Charlie",
        "appraisedValue": "3000"
    }
}

API 端点

健康检查

GET /health - 检查服务健康状态

账本操作

POST /api/v1/ledger/init - 初始化账本

资产操作

GET /api/v1/assets - 获取所有资产
POST /api/v1/assets - 创建新资产
GET /api/v1/assets/{id} - 根据ID获取资产
PUT /api/v1/assets/{id} - 更新资产信息
PUT /api/v1/assets/{id}/transfer - 转移资产所有权

区块链操作

GET /api/v1/blockchain/height - 获取当前区块高度
GET /api/v1/blockchain/info - 获取区块链信息

交易操作

GET /api/v1/transactions/{txid} - 根据交易ID查询交易详情

使用示例

获取区块高度

curl -X GET "http://localhost:8080/api/v1/blockchain/height"

响应示例：

{
  "success": true,
  "message": "Block height retrieved successfully",
  "data": {
    "height": 12345
  }
}

获取区块链信息

curl -X GET "http://localhost:8080/api/v1/blockchain/info"

响应示例：

{
  "success": true,
  "message": "Chain information retrieved successfully",
  "data": {
    "height": 12345,
    "chainName": "mychannel"
  }
}

查询交易详情

curl -X GET "http://localhost:8080/api/v1/transactions/{txid}"

响应示例：

{
  "success": true,
  "message": "Transaction details retrieved successfully",
  "data": {
    "transactionId": "d341d13093e72e201f73725b4d93b45b2e261fd7440e3e624f141f6f8d509495",
    "blockNumber": 79,
    "blockHash": "block-hash-for-d341d130",
    "timestamp": "2025-06-12T13:38:14+08:00",
    "channelId": "mychannel",
    "creatorMspId": "",
    "creatorId": "",
    "endorsers": null,
    "chaincodeId": "",
    "function": "",
    "arguments": null,
    "response": {
      "status": 200,
      "message": "Transaction completed successfully",
      "payload": ""
    },
    "validationCode": "VALID",
    "rawTransaction": {
      "hasData": true,
      "size": 4822
    }
  }
}

错误处理

API使用标准HTTP状态码表示请求结果：

200 OK - 请求成功
201 Created - 资源创建成功
400 Bad Request - 请求参数错误
404 Not Found - 资源未找到
500 Internal Server Error - 服务器内部错误

错误响应格式：

{
    "success": false,
    "message": "错误描述信息"
}

配置

服务使用以下环境变量进行配置：

PORT - 服务端口（默认：8080）
CHAINCODE_NAME - 链码名称（默认：basic）
CHANNEL_NAME - 通道名称（默认：mychannel）

证书配置

确保以下路径存在正确的证书文件：

../../test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts
../../test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore
../../test-network/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt

使用示例

使用curl测试API：

# 健康检查
curl http://localhost:8080/health

# 初始化账本
curl -X POST http://localhost:8080/api/v1/ledger/init

# 创建资产
curl -X POST http://localhost:8080/api/v1/assets \
  -H "Content-Type: application/json" \
  -d '{
    "id": "asset123",
    "color": "red",
    "size": "10",
    "owner": "Alice",
    "appraisedValue": "2000"
  }'

# 查询所有资产
curl http://localhost:8080/api/v1/assets

# 查询特定资产
curl http://localhost:8080/api/v1/assets/asset123

# 转移资产
curl -X PUT http://localhost:8080/api/v1/assets/asset123/transfer \
  -H "Content-Type: application/json" \
  -d '{"newOwner": "Bob"}'

容器化部署

使用Docker构建和运行

# 构建镜像
docker build -t spiderman -f docker/Dockerfile .

# 运行容器
docker run -p 8080:8080 spiderman

使用Docker Compose

# 启动服务
cd docker && docker-compose up -d

# 查看日志
cd docker && docker-compose logs -f

# 停止服务
cd docker && docker-compose down

项目结构

.
├── main.go              # 主服务入口和路由配置
├── fabric_client.go     # Fabric客户端封装
├── api_handler.go       # HTTP请求处理器
├── docs/                # Swagger生成的API文档
│   ├── docs.go         # Go文档
│   ├── swagger.json    # JSON格式API规范
│   └── swagger.yaml    # YAML格式API规范
├── go.mod              # Go模块配置
├── go.sum              # 依赖项校验和
├── docker/             # Docker相关文件
│   ├── Dockerfile      # Docker镜像构建文件
│   ├── docker-compose.yml  # Docker Compose配置
│   └── DOCKER_GUIDE.md # Docker使用指南
├── start.sh           # 启动脚本
├── test_api.sh        # API测试脚本
└── README.md          # 项目文档

📖 Swagger 配置

本项目的 Swagger 文档配置现在支持通过 config.env 文件动态设置 host 和 port。

配置方式

在 config.env 文件中设置以下参数：

# Server Configuration
HOST=localhost    # Swagger 文档的主机地址
PORT=8888        # Swagger 文档的端口号

访问地址

启动服务后，Swagger 文档将在以下地址可用：

Swagger UI: http://{HOST}:{PORT}/swagger/index.html
API 基础路径: http://{HOST}:{PORT}/api/v1

例如，使用默认配置时：

Swagger UI: http://localhost:8888/swagger/index.html
API 基础路径: http://localhost:8888/api/v1

自定义配置示例

如果你需要在不同的主机或端口上运行：

# config.env
HOST=192.168.1.100
PORT=9090

服务启动后会自动更新 Swagger 配置，无需手动重新生成文档。

🔧 故障排除

API访问错误解决方案

如果在使用curl访问API时遇到错误，请按以下步骤排查：

1. JSON反序列化错误

错误信息: cannot unmarshal number into Go struct field Asset.appraisedValue of type string

原因: Hyperledger Fabric链码中的初始数据的appraisedValue字段是数字类型，但API代码期望字符串类型。

解决方案: 已在pkg/models/asset.go中实现自定义JSON反序列化方法：

// 自定义UnmarshalJSON方法处理数字和字符串类型的appraisedValue
func (a *Asset) UnmarshalJSON(data []byte) error {
    // 支持string, float64, int, int64类型的自动转换
}

2. gRPC连接超时错误

错误信息: gRPC error: context deadline exceeded

原因: Hyperledger Fabric网络没有运行或配置不正确。

解决方案:

确保Fabric网络正在运行：

# 在fabric-samples/test-network目录下
./network.sh up createChannel -ca -c mychannel
./network.sh deployCC -ccn basic -ccp ../asset-transfer-basic/chaincode-go -ccl go

检查网络状态：

docker ps  # 应该看到peer, orderer, ca等容器

验证配置文件中的路径：

# config.env中的CRYPTO_PATH是否指向正确的证书目录
CRYPTO_PATH=../../test-network/organizations/peerOrganizations/org1.example.com

3. 端口冲突

错误信息: bind: address already in use

解决方案:

# 查找占用端口的进程
lsof -i :8888
# 停止进程
kill -9 <PID>

4. 证书路径错误

错误信息: failed to read certificate file 或 failed to read private key file

解决方案:

检查证书路径是否存在：

ls -la ../../test-network/organizations/peerOrganizations/org1.example.com/

确保当前目录正确：
```
pwd  # 应该在项目根目录
```

测试API连接

健康检查:
```
curl http://localhost:8888/health
```

初始化账本 (首次使用):

curl -X POST http://localhost:8888/api/v1/ledger/init

获取所有资产:

curl http://localhost:8888/api/v1/assets

常见问题

Q: API返回空数组{"success":true,"data":[]}？ A: 账本可能没有初始化，运行初始化命令：

curl -X POST http://localhost:8888/api/v1/ledger/init

Q: Swagger UI无法访问？ A: 确保在开发环境下运行：

ENVIRONMENT=development go run cmd/server/main.go

Q: 修改代码后错误依然存在？ A: 清理缓存并重新启动：

go clean -cache
go mod tidy
go run cmd/server/main.go

12 KiB Raw Permalink Blame History

Spiderman - Hyperledger Fabric Asset Transfer REST API

功能特性

先决条件

安装和运行

API 接口

基础URL

🔍 Swagger API 文档

健康检查

1. 初始化账本

2. 获取所有资产

3. 创建资产

4. 根据ID查询资产

5. 转移资产所有权

6. 更新资产

API 端点

健康检查

账本操作

资产操作

区块链操作

交易操作

使用示例

获取区块高度

获取区块链信息

查询交易详情

错误处理

配置

证书配置

使用示例

容器化部署

使用Docker构建和运行

使用Docker Compose

项目结构

📖 Swagger 配置

配置方式

访问地址

自定义配置示例

🔧 故障排除

API访问错误解决方案

1. JSON反序列化错误

2. gRPC连接超时错误

3. 端口冲突

4. 证书路径错误

测试API连接

常见问题

12 KiB

Raw Permalink Blame History