richard/plates-server

Fork 0

Files

richarjiang 02f21f0858 feat(water-records): 优化创建喝水记录和获取记录列表的日期处理逻辑

2025-09-02 15:27:21 +08:00

11 KiB

Raw Permalink 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

最佳实践

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

完整的客户端封装示例

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封装提供了完整的喝水记录管理功能，可以直接在客户端项目中使用。

11 KiB Raw Permalink Blame History Unescape Escape

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

概述

基础信息

认证

API 接口列表

1. 创建喝水记录

2. 获取喝水记录列表

3. 更新喝水记录

4. 删除喝水记录

5. 更新每日喝水目标

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

错误处理

常见错误码

错误响应格式

客户端错误处理示例

数据类型说明

WaterRecordSource 枚举

日期格式

最佳实践

完整的客户端封装示例

11 KiB

Raw Permalink Blame History