richard/plates-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1b7132a325d47c32cafe275a049bb17def5f9e78
plates-server/docs/water-records-api.md

11 KiB
Raw Blame History

喝水记录 API 客户端接入说明

概述

喝水记录 API 提供了完整的喝水记录管理功能，包括记录创建、查询、更新、删除，以及喝水目标设置和统计查询等功能。

基础信息

  • Base URL: https://your-api-domain.com/api
  • 认证方式: JWT Bearer Token
  • Content-Type: application/json

认证

所有 API 请求都需要在请求头中包含有效的 JWT Token：

Authorization: Bearer <your-jwt-token>

API 接口列表

1. 创建喝水记录

接口地址: POST /water-records

描述: 创建一条新的喝水记录

请求参数:

{
  "amount": 250,                           // 必填，喝水量（毫升），范围：1-5000
  "recordedAt": "2023-12-01T10:00:00.000Z", // 可选，记录时间，默认为当前时间
  "source": "Manual",                      // 可选，记录来源：Manual(手动) | Auto(自动)
  "note": "早晨第一杯水"                    // 可选，备注，最大100字符
}

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": 1,
    "amount": 250,
    "recordedAt": "2023-12-01T10:00:00.000Z",
    "note": "早晨第一杯水",
    "createdAt": "2023-12-01T10:00:00.000Z",
    "updatedAt": "2023-12-01T10:00:00.000Z"
  }
}

客户端示例代码:

// JavaScript/TypeScript
const createWaterRecord = async (recordData) => {
  const response = await fetch('/api/water-records', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(recordData)
  });
  return response.json();
};

// 使用示例
const result = await createWaterRecord({
  amount: 250,
  note: "早晨第一杯水"
});

2. 获取喝水记录列表

接口地址: GET /water-records

描述: 获取用户的喝水记录列表，支持分页和日期筛选

查询参数:

  • startDate (可选): 开始日期，格式：YYYY-MM-DD
  • endDate (可选): 结束日期，格式：YYYY-MM-DD
  • page (可选): 页码，默认1
  • limit (可选): 每页数量，默认20，最大100

请求示例:

GET /water-records?startDate=2023-12-01&endDate=2023-12-31&page=1&limit=20

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "amount": 250,
        "recordedAt": "2023-12-01T10:00:00.000Z",
        "note": "早晨第一杯水",
        "createdAt": "2023-12-01T10:00:00.000Z",
        "updatedAt": "2023-12-01T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

客户端示例代码:

const getWaterRecords = async (params = {}) => {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`/api/water-records?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.json();
};

// 使用示例
const records = await getWaterRecords({
  startDate: '2023-12-01',
  endDate: '2023-12-31',
  page: 1,
  limit: 20
});

3. 更新喝水记录

接口地址: PUT /water-records/:id

描述: 更新指定的喝水记录

路径参数:

  • id: 记录ID

请求参数 (所有字段都是可选的):

{
  "amount": 300,                           // 可选，喝水量（毫升）
  "recordedAt": "2023-12-01T11:00:00.000Z", // 可选，记录时间
  "source": "Manual",                      // 可选，记录来源
  "note": "修改后的备注"                    // 可选，备注
}

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "id": 1,
    "amount": 300,
    "recordedAt": "2023-12-01T11:00:00.000Z",
    "note": "修改后的备注",
    "createdAt": "2023-12-01T10:00:00.000Z",
    "updatedAt": "2023-12-01T11:30:00.000Z"
  }
}

客户端示例代码:

const updateWaterRecord = async (recordId, updateData) => {
  const response = await fetch(`/api/water-records/${recordId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(updateData)
  });
  return response.json();
};

4. 删除喝水记录

接口地址: DELETE /water-records/:id

描述: 删除指定的喝水记录

路径参数:

  • id: 记录ID

响应: HTTP 204 No Content (成功删除)

客户端示例代码:

const deleteWaterRecord = async (recordId) => {
  const response = await fetch(`/api/water-records/${recordId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.status === 204;
};

5. 更新每日喝水目标

接口地址: PUT /water-records/goal/daily

描述: 设置或更新用户的每日喝水目标

请求参数:

{
  "dailyWaterGoal": 2000  // 必填，每日喝水目标（毫升），范围：500-10000
}

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "dailyWaterGoal": 2000,
    "updatedAt": "2023-12-01T12:00:00.000Z"
  }
}

客户端示例代码:

const updateWaterGoal = async (goalAmount) => {
  const response = await fetch('/api/water-records/goal/daily', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ dailyWaterGoal: goalAmount })
  });
  return response.json();
};

6. 获取指定日期的喝水统计

接口地址: GET /water-records/stats

描述: 获取指定日期的喝水统计信息，包括总量、完成率等

查询参数:

  • date (可选): 查询日期，格式：YYYY-MM-DD，不传则默认为今天

请求示例:

GET /water-records/stats?date=2023-12-01

响应示例:

{
  "success": true,
  "message": "操作成功",
  "data": {
    "date": "2023-12-01",
    "totalAmount": 1500,        // 当日总喝水量（毫升）
    "dailyGoal": 2000,          // 每日目标（毫升）
    "completionRate": 75.0,     // 完成率（百分比）
    "recordCount": 6,           // 记录次数
    "records": [                // 当日所有记录
      {
        "id": 1,
        "amount": 250,
        "recordedAt": "2023-12-01T08:00:00.000Z",
        "note": "早晨第一杯水"
      },
      {
        "id": 2,
        "amount": 300,
        "recordedAt": "2023-12-01T10:30:00.000Z",
        "note": null
      }
    ]
  }
}

客户端示例代码:

const getWaterStats = async (date) => {
  const params = date ? `?date=${date}` : '';
  const response = await fetch(`/api/water-records/stats${params}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.json();
};

// 使用示例
const todayStats = await getWaterStats(); // 获取今天的统计
const specificDateStats = await getWaterStats('2023-12-01'); // 获取指定日期的统计

错误处理

常见错误码

  • 400 Bad Request: 请求参数错误
  • 401 Unauthorized: 未授权，Token无效或过期
  • 404 Not Found: 资源不存在
  • 422 Unprocessable Entity: 数据验证失败
  • 500 Internal Server Error: 服务器内部错误

错误响应格式

{
  "success": false,
  "message": "错误描述",
  "error": {
    "code": "ERROR_CODE",
    "details": "详细错误信息"
  }
}

客户端错误处理示例

const handleApiCall = async (apiFunction) => {
  try {
    const result = await apiFunction();
    if (result.success) {
      return result.data;
    } else {
      throw new Error(result.message);
    }
  } catch (error) {
    console.error('API调用失败:', error.message);
    // 根据错误类型进行相应处理
    if (error.status === 401) {
      // Token过期，重新登录
      redirectToLogin();
    }
    throw error;
  }
};

数据类型说明

WaterRecordSource 枚举

enum WaterRecordSource {
  Manual = 'Manual',    // 手动记录
  Auto = 'Auto'         // 自动记录
}

日期格式

  • 所有日期时间字段使用 ISO 8601 格式：YYYY-MM-DDTHH:mm:ss.sssZ
  • 查询参数中的日期使用简化格式：YYYY-MM-DD

最佳实践

  1. 错误处理: 始终检查响应的 success 字段，并妥善处理错误情况
  2. Token管理: 实现Token自动刷新机制，避免因Token过期导致的请求失败
  3. 数据验证: 在发送请求前进行客户端数据验证，提升用户体验
  4. 缓存策略: 对于统计数据等相对稳定的信息，可以实现适当的缓存策略
  5. 分页处理: 处理列表数据时，注意分页信息，避免一次性加载过多数据

完整的客户端封装示例

class WaterRecordsAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    const config = {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`,
        ...options.headers
      },
      ...options
    };

    const response = await fetch(url, config);
    const data = await response.json();

    if (!data.success) {
      throw new Error(data.message);
    }

    return data.data;
  }

  // 创建喝水记录
  async createRecord(recordData) {
    return this.request('/water-records', {
      method: 'POST',
      body: JSON.stringify(recordData)
    });
  }

  // 获取记录列表
  async getRecords(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    return this.request(`/water-records?${queryString}`);
  }

  // 更新记录
  async updateRecord(recordId, updateData) {
    return this.request(`/water-records/${recordId}`, {
      method: 'PUT',
      body: JSON.stringify(updateData)
    });
  }

  // 删除记录
  async deleteRecord(recordId) {
    await this.request(`/water-records/${recordId}`, {
      method: 'DELETE'
    });
    return true;
  }

  // 更新喝水目标
  async updateGoal(goalAmount) {
    return this.request('/water-records/goal/daily', {
      method: 'PUT',
      body: JSON.stringify({ dailyWaterGoal: goalAmount })
    });
  }

  // 获取统计数据
  async getStats(date) {
    const params = date ? `?date=${date}` : '';
    return this.request(`/water-records/stats${params}`);
  }
}

// 使用示例
const api = new WaterRecordsAPI('https://your-api-domain.com/api', 'your-jwt-token');

// 创建记录
const newRecord = await api.createRecord({
  amount: 250,
  note: '早晨第一杯水'
});

// 获取今日统计
const todayStats = await api.getStats();

这个API封装提供了完整的喝水记录管理功能，可以直接在客户端项目中使用。