likegears/material_texture
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
material_texture/docs/API.md
likegears 85ba15c564 Initial commit: Material Texture API service 
- Go + Gin + GORM + PostgreSQL backend
- RESTful API for material management
- Docker deployment support
- Database partitioning for billion-scale data
- API documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-11 15:29:49 +08:00

11 KiB
Raw Permalink Blame History

材质管理系统 API 文档

基础信息

  • Base URL: http://10.99.98.248:8081/api/v1
  • 认证方式: API Token
  • Content-Type: application/json

认证

所有API请求需要在Header中携带Token：

X-API-Token: seatons3d

错误响应示例：

{
  "code": 401,
  "message": "missing API token"
}

通用响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

分页响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 303,
    "page": 1,
    "page_size": 20
  }
}

错误响应

{
  "code": 400,
  "message": "error description"
}

错误码

状态码 说明
200 成功
201 创建成功
400 请求参数错误
401 未授权（Token无效）
404 资源不存在
500 服务器内部错误

材质管理接口

1. 获取材质列表

GET /materials

请求参数（Query）

参数 类型 必填 说明
page int 否 页码，默认1
page_size int 否 每页数量，默认20，最大100
name string 否 按名称模糊搜索

请求示例

curl -H "X-API-Token: seatons3d" \
  "http://10.99.98.248:8081/api/v1/materials?page=1&page_size=10&name=red"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 4,
        "name": "dgnColor4",
        "diffuse_r": 255,
        "diffuse_g": 0,
        "diffuse_b": 0,
        "alpha": 255,
        "shininess": 20,
        "specular_r": 230,
        "specular_g": 230,
        "specular_b": 230,
        "ambient_r": 50,
        "ambient_g": 50,
        "ambient_b": 50,
        "metallic": 0,
        "roughness": 0,
        "reflectance": 0,
        "created_at": "2025-12-09T09:53:33.209555Z",
        "updated_at": "2025-12-09T09:53:33.209555Z"
      }
    ],
    "total": 303,
    "page": 1,
    "page_size": 10
  }
}

2. 添加材质

POST /materials

请求Body

字段 类型 必填 说明
name string 是 材质名称
diffuse_r float 否 漫反射-红 (0-255)
diffuse_g float 否 漫反射-绿 (0-255)
diffuse_b float 否 漫反射-蓝 (0-255)
alpha float 否 透明度 (0-255)
shininess float 否 光泽度
specular_r float 否 高光-红 (0-255)
specular_g float 否 高光-绿 (0-255)
specular_b float 否 高光-蓝 (0-255)
ambient_r float 否 环境光-红 (0-255)
ambient_g float 否 环境光-绿 (0-255)
ambient_b float 否 环境光-蓝 (0-255)
metallic float 否 金属度
roughness float 否 粗糙度
reflectance float 否 反射率

请求示例

curl -X POST -H "X-API-Token: seatons3d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "红色金属",
    "diffuse_r": 255,
    "diffuse_g": 50,
    "diffuse_b": 50,
    "alpha": 255,
    "metallic": 0.8,
    "roughness": 0.2
  }' \
  "http://10.99.98.248:8081/api/v1/materials"

响应示例

{
  "code": 0,
  "message": "created",
  "data": {
    "id": 305,
    "name": "红色金属",
    "diffuse_r": 255,
    "diffuse_g": 50,
    "diffuse_b": 50,
    "alpha": 255,
    "shininess": 0,
    "specular_r": 0,
    "specular_g": 0,
    "specular_b": 0,
    "ambient_r": 0,
    "ambient_g": 0,
    "ambient_b": 0,
    "metallic": 0.8,
    "roughness": 0.2,
    "reflectance": 0.5,
    "created_at": "2025-12-09T18:02:22.846141Z",
    "updated_at": "2025-12-09T18:02:22.846141Z"
  }
}

3. 获取材质详情

GET /materials/:id

路径参数

参数 类型 说明
id int 材质ID

请求示例

curl -H "X-API-Token: seatons3d" \
  "http://10.99.98.248:8081/api/v1/materials/4"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4,
    "name": "dgnColor4",
    "diffuse_r": 255,
    "diffuse_g": 0,
    "diffuse_b": 0,
    "alpha": 255,
    "shininess": 20,
    "specular_r": 230,
    "specular_g": 230,
    "specular_b": 230,
    "ambient_r": 50,
    "ambient_g": 50,
    "ambient_b": 50,
    "metallic": 0,
    "roughness": 0,
    "reflectance": 0,
    "created_at": "2025-12-09T09:53:33.209555Z",
    "updated_at": "2025-12-09T09:53:33.209555Z"
  }
}

错误响应

{
  "code": 404,
  "message": "material not found"
}

4. 编辑材质

PUT /materials/:id

路径参数

参数 类型 说明
id int 材质ID

请求Body

同"添加材质"接口

请求示例

curl -X PUT -H "X-API-Token: seatons3d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "红色金属-更新版",
    "diffuse_r": 200,
    "diffuse_g": 100,
    "diffuse_b": 50,
    "alpha": 255,
    "metallic": 0.9,
    "roughness": 0.1
  }' \
  "http://10.99.98.248:8081/api/v1/materials/305"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 305,
    "name": "红色金属-更新版",
    "diffuse_r": 200,
    "diffuse_g": 100,
    "diffuse_b": 50,
    "alpha": 255,
    ...
  }
}

5. 删除材质

DELETE /materials/:id

路径参数

参数 类型 说明
id int 材质ID

请求示例

curl -X DELETE -H "X-API-Token: seatons3d" \
  "http://10.99.98.248:8081/api/v1/materials/305"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 305
  }
}

注意: 删除材质会级联删除所有相关的绑定关系

绑定管理接口

6. 绑定材质到多个Group

POST /materials/:id/bindings

将一个材质绑定到多个叶子节点（group_id），支持幂等操作（重复绑定不会报错）。

路径参数

参数 类型 说明
id int 材质ID

请求Body

字段 类型 必填 说明
group_ids string[] 是 叶子节点ID数组

请求示例

curl -X POST -H "X-API-Token: seatons3d" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["node_001", "node_002", "node_003"]
  }' \
  "http://10.99.98.248:8081/api/v1/materials/4/bindings"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "material_id": 4,
    "group_ids": ["node_001", "node_002", "node_003"]
  }
}

7. 解绑材质与Group

DELETE /materials/:id/bindings

路径参数

参数 类型 说明
id int 材质ID

请求Body

字段 类型 必填 说明
group_ids string[] 是 要解绑的叶子节点ID数组

请求示例

curl -X DELETE -H "X-API-Token: seatons3d" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["node_001", "node_002"]
  }' \
  "http://10.99.98.248:8081/api/v1/materials/4/bindings"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "material_id": 4,
    "unbound": ["node_001", "node_002"]
  }
}

8. 获取材质关联的所有Group（分页）

GET /materials/:id/groups

路径参数

参数 类型 说明
id int 材质ID

请求参数（Query）

参数 类型 必填 说明
page int 否 页码，默认1
page_size int 否 每页数量，默认20，最大100

请求示例

curl -H "X-API-Token: seatons3d" \
  "http://10.99.98.248:8081/api/v1/materials/4/groups?page=1&page_size=10"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      "20251021105717834754",
      "20251021105717834758",
      "20251021105717834762"
    ],
    "total": 22,
    "page": 1,
    "page_size": 10
  }
}

9. 根据Group IDs批量查询关联材质

POST /groups/materials

根据一个或多个叶子节点ID，查询它们关联的材质详情。

请求Body

字段 类型 必填 说明
group_ids string[] 是 叶子节点ID数组

请求示例

curl -X POST -H "X-API-Token: seatons3d" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["202510211057245681447", "aDsIXMkjxdm2CDUj9gTvf"]
  }' \
  "http://10.99.98.248:8081/api/v1/groups/materials"

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "group_id": "202510211057245681447",
      "material": {
        "id": 4,
        "name": "dgnColor4",
        "diffuse_r": 255,
        "diffuse_g": 0,
        "diffuse_b": 0,
        "alpha": 255,
        "shininess": 20,
        "specular_r": 230,
        "specular_g": 230,
        "specular_b": 230,
        "ambient_r": 50,
        "ambient_g": 50,
        "ambient_b": 50,
        "metallic": 0,
        "roughness": 0,
        "reflectance": 0,
        "created_at": "2025-12-09T09:53:33.209555Z",
        "updated_at": "2025-12-09T09:53:33.209555Z"
      }
    },
    {
      "group_id": "aDsIXMkjxdm2CDUj9gTvf",
      "material": {
        "id": -1,
        "name": "默认值",
        "diffuse_r": 192,
        "diffuse_g": 192,
        "diffuse_b": 192,
        ...
      }
    }
  ]
}

注意: 如果某个group_id没有绑定材质，则不会出现在返回结果中

健康检查

GET /health

此接口无需认证。

请求示例

curl http://10.99.98.248:8081/health

响应示例

{
  "status": "ok"
}

数据模型

Material（材质）

字段 类型 说明
id int64 材质ID（主键）
name string 材质名称
diffuse_r float64 漫反射-红 (0-255)
diffuse_g float64 漫反射-绿 (0-255)
diffuse_b float64 漫反射-蓝 (0-255)
alpha float64 透明度 (0-255)
shininess float64 光泽度
specular_r float64 高光-红 (0-255)
specular_g float64 高光-绿 (0-255)
specular_b float64 高光-蓝 (0-255)
ambient_r float64 环境光-红 (0-255)
ambient_g float64 环境光-绿 (0-255)
ambient_b float64 环境光-蓝 (0-255)
metallic float64 金属度
roughness float64 粗糙度
reflectance float64 反射率
created_at timestamp 创建时间
updated_at timestamp 更新时间

MaterialBinding（材质绑定）

字段 类型 说明
id int64 绑定ID（主键）
material_id int64 材质ID（外键）
group_id string 叶子节点ID
created_at timestamp 创建时间
Reference in New Issue View Git Blame Copy Permalink