自学内容网 自学内容网
自学内容网 > 正文

接口文档讲解

🕗 发布于 2024-11-16 23:05 前端  服务器  

用户管理模块

1.1 用户注册
1.1.1 基本信息
  • 请求路径：/api/register
  • 请求方式：POST
  • 接口描述：用户注册接口，传入用户名、密码、邮箱等。
1.1.2 请求参数
  • 参数格式：application/json
  • 参数说明：
    • username: 用户名
    • password: 密码
    • email: 邮箱
1.1.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
1.1.4 请求数据样例

json

复制

{
  "username": "example_username",
  "password": "example_password",
  "email": "example_email@example.com"
}
1.1.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "user_id": 123456
  }
}
1.2 用户登录
1.2.1 基本信息
  • 请求路径：/api/login
  • 请求方式：POST
  • 接口描述：用户登录接口，传入用户名/邮箱和密码，返回token（JWT）。
1.2.2 请求参数
  • 参数格式：application/json
  • 参数说明：
    • username: 用户名/邮箱
    • password: 密码
1.2.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据，token（JWT）
1.2.4 请求数据样例

json

复制

{
  "username": "example_username",
  "password": "example_password"
}
1.2.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": "eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoi6YeR5bq4IiwiaWQiOjEsInVzZXJuYW1lIjoiamlueW9uZyIsImV4cCI6MTY2MjIwNzA0OH0.KkUc_CXJZJ8Dd063eImx4H9Ojfrr6XMJ-yVzaWCVZCo"
}
1.3 用户登出
1.3.1 基本信息
  • 请求路径：/api/logout
  • 请求方式：POST
  • 接口描述：用户登出接口，清除会话信息。（退出登录）
1.3.2 请求参数
  • 参数格式：无
1.3.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
1.3.4 请求数据样例

无

1.3.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": null
}
相关代码

以下是使用 Express 实现的用户管理模块代码，包括用户注册、登录和登出接口：

const express = require('express');
const jwt = require('jsonwebtoken');
const bodyParser = require('body-parser');
const app = express();

// 使用 bodyParser 解析 JSON 请求体
app.use(bodyParser.json()); // 新版本的node已内置对body的支持 无需 body-parser

// 模拟数据库和密钥
const users = [];
const JWT_SECRET = 'your_jwt_secret_key';

// 用户注册接口
app.post('/api/register', (req, res) => {
    const { username, password, email } = req.body;

    // 验证是否提供了所有必需字段
    if (!username || !password || !email) {
        return res.json({ code: 0, msg: 'Missing required fields', data: null });
    }

    // 模拟用户 ID 生成
    const userId = users.length + 1;
    users.push({ userId, username, password, email });

    res.json({
        code: 1,
        msg: 'success',
        data: { user_id: userId }
    });
});

// 用户登录接口
app.post('/api/login', (req, res) => {
    const { username, password } = req.body;

    // 验证是否提供了所有必需字段
    if (!username || !password) {
        return res.json({ code: 0, msg: 'Missing username or password', data: null });
    }

    // 查找用户
    const user = users.find(
        (u) => (u.username === username || u.email === username) && u.password === password
    );

    if (!user) {
        return res.json({ code: 0, msg: 'Invalid username or password', data: null });
    }

    // 创建 JWT token
    const token = jwt.sign({ userId: user.userId, username: user.username }, JWT_SECRET, { expiresIn: '1h' });

    res.json({
        code: 1,
        msg: 'success',
        data: token
    });
});

// 用户登出接口
app.post('/api/logout', (req, res) => {
    // 在这里可以进行会话或 token 的清除（如果有的话）
    res.json({
        code: 1,
        msg: 'success',
        data: null
    });
});

// 启动服务器
const PORT = 3000;
app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

景点信息模块

2.1 获取单个景点的详细信息
2.1.1 基本信息
  • 请求路径：/api/attractions/{id}
  • 请求方式：GET
  • 接口描述：获取单个景点的详细信息，包括名称、地址、图片、简介等。
2.1.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 景点ID
2.1.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
2.1.4 请求数据样例

复制

/api/attractions/1
2.1.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "景点名称",
    "address": "地址",
    "images": ["图片1", "图片2", "图片3"],
    "introduction": "简介"
  }
}
2.2 获取指定景点的评论列表
2.2.1 基本信息
  • 请求路径：/api/attractions/{id}/reviews
  • 请求方式：GET
  • 接口描述：获取指定景点的评论列表，支持分页。
2.2.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 景点ID
2.2.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
2.2.4 请求数据样例

复制

/api/attractions/1/reviews
2.2.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "total": 10,
    "rows": [
      {
        "id": 1,
        "user_id": 123456,
        "content": "评论内容",
        "rating": 4.5,
        "create_time": "2022-09-01T23:06:29"
      },
      {
        "id": 2,
        "user_id": 789012,
        "content": "评论内容",
        "rating": 3.0,
        "create_time": "2022-09-01T23:06:29"
      }
    ]
  }
}
2.3 用户提交评论和评分
2.3.1 基本信息
  • 请求路径：/api/attractions/{id}/reviews
  • 请求方式：POST
  • 接口描述：用户提交评论和评分。
2.3.2 请求参数
  • 参数格式：application/json
  • 参数说明：
    • id: 景点ID
    • content: 评论内容
    • rating: 评分
2.3.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
2.3.4 请求数据样例

json

复制

{
  "id": 1,
  "content": "非常好，值得一去",
  "rating": 5.0
}
2.3.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "评论成功",
  "data": {
    "review_id": 123456
  }
}
2.4 获取景点的平均评分
2.4.1 基本信息
  • 请求路径：/api/attractions/{id}/average-rating
  • 请求方式：GET
  • 接口描述：获取景点的平均评分。
2.4.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 景点ID
2.4.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
2.4.4 请求数据样例

复制

/api/attractions/1/average-rating
2.4.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "average_rating": 4.5
  }
}
2.5 获取景点的图片和视频
2.5.1 基本信息
  • 请求路径：/api/attractions/{id}/media
  • 请求方式：GET
  • 接口描述：获取景点的图片和视频。
2.5.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 景点ID
2.5.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
2.5.4 请求数据样例

复制

/api/attractions/1/media
2.5.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "images": ["图片1", "图片2", "图片3"],
    "videos": ["视频1", "视频2", "视频3"]
  }
}
相关代码

以下是使用 Koa 实现的景点信息模块代码，包括获取单个景点详情、评论列表、提交评论、平均评分和多媒体信息接口：

const Koa = require('koa');
const Router = require('@koa/router');
const bodyParser = require('koa-bodyparser');

const app = new Koa();
const router = new Router();

// 模拟数据库
const attractions = {
  1: {
    id: 1,
    name: '景点名称',
    address: '地址',
    images: ['图片1', '图片2', '图片3'],
    introduction: '简介',
    reviews: [
      { id: 1, user_id: 123456, content: '评论内容', rating: 4.5, create_time: '2022-09-01T23:06:29' },
      { id: 2, user_id: 789012, content: '评论内容', rating: 3.0, create_time: '2022-09-01T23:06:29' },
    ],
    media: { images: ['图片1', '图片2', '图片3'], videos: ['视频1', '视频2', '视频3'] }
  }
};

// 中间件
app.use(bodyParser());  // 新版本 node 已内置 无需插件

// 获取单个景点的详细信息
router.get('/api/attractions/:id', (ctx) => {
  const { id } = ctx.params;
  const attraction = attractions[id];

  if (attraction) {
    ctx.body = { code: 1, msg: 'success', data: attraction };
  } else {
    ctx.body = { code: 0, msg: 'Attraction not found', data: null };
  }
});

// 获取指定景点的评论列表
router.get('/api/attractions/:id/reviews', (ctx) => {
  const { id } = ctx.params;
  const attraction = attractions[id];

  if (attraction) {
    ctx.body = {
      code: 1,
      msg: 'success',
      data: {
        total: attraction.reviews.length,
        rows: attraction.reviews
      }
    };
  } else {
    ctx.body = { code: 0, msg: 'Attraction not found', data: null };
  }
});

// 用户提交评论和评分
router.post('/api/attractions/:id/reviews', (ctx) => {
  const { id } = ctx.params;
  const { content, rating } = ctx.request.body;
  const attraction = attractions[id];

  if (attraction && content && rating) {
    const newReview = {
      id: attraction.reviews.length + 1,
      user_id: Math.floor(Math.random() * 1000000),
      content,
      rating,
      create_time: new Date().toISOString()
    };

    attraction.reviews.push(newReview);
    ctx.body = { code: 1, msg: '评论成功', data: { review_id: newReview.id } };
  } else {
    ctx.body = { code: 0, msg: 'Failed to submit review', data: null };
  }
});

// 获取景点的平均评分
router.get('/api/attractions/:id/average-rating', (ctx) => {
  const { id } = ctx.params;
  const attraction = attractions[id];

  if (attraction) {
    const totalRating = attraction.reviews.reduce((sum, review) => sum + review.rating, 0);
    const averageRating = (totalRating / attraction.reviews.length) || 0;

    ctx.body = {
      code: 1,
      msg: 'success',
      data: { average_rating: averageRating.toFixed(1) }
    };
  } else {
    ctx.body = { code: 0, msg: 'Attraction not found', data: null };
  }
});

// 获取景点的图片和视频
router.get('/api/attractions/:id/media', (ctx) => {
  const { id } = ctx.params;
  const attraction = attractions[id];

  if (attraction) {
    ctx.body = { code: 1, msg: 'success', data: attraction.media };
  } else {
    ctx.body = { code: 0, msg: 'Attraction not found', data: null };
  }
});

// 将路由加载到应用中
app.use(router.routes()).use(router.allowedMethods());

// 启动服务器
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

旅游路线模块

3.1 获取推荐的旅游路线列表
3.1.1 基本信息
  • 请求路径：/api/routes
  • 请求方式：GET
  • 接口描述：获取推荐的旅游路线列表，可以根据景点、时间、距离等过滤。
3.1.2 请求参数
  • 参数格式：queryString
  • 参数说明：
    • attraction_ids: 景点ID列表，多个ID用逗号分隔
    • start_time: 开始时间
    • end_time: 结束时间
    • distance: 最大距离限制
3.1.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
3.1.4 请求数据样例

复制

/api/routes?attraction_ids=1,2,3&start_time=2022-09-01&end_time=2022-09-05&distance=50
3.1.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "路线名称",
      "attraction_ids": [1, 2, 3],
      "start_time": "2022-09-01",
      "end_time": "2022-09-05",
      "distance": 50
    },
    {
      "id": 2,
      "name": "路线名称",
      "attraction_ids": [1, 2, 3],
      "start_time": "2022-09-01",
      "end_time": "2022-09-05",
      "distance": 50
    }
  ]
}
3.2 获取单条旅游路线的详细信息
3.2.1 基本信息
  • 请求路径：/api/routes/{id}
  • 请求方式：GET
  • 接口描述：获取单条旅游路线的详细信息。
3.2.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 路线ID
3.2.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
3.2.4 请求数据样例

复制

/api/routes/1
3.2.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "路线名称",
    "attraction_ids": [1, 2, 3],
    "start_time": "2022-09-01",
    "end_time": "2022-09-05",
    "distance": 50
  }
}
相关代码

以下是使用 NestJS 实现的旅游路线模块代码，包括获取推荐路线列表和单条路线详细信息的接口：

代码结构

  1. Controller：定义 HTTP 请求的路由和处理逻辑。
  2. Service：处理业务逻辑。
  3. DTO：定义数据传输对象，用于校验和规范接口请求参数和响应数据格式。

Controller 和 Service 代码

创建 DTO 文件

首先，创建两个 DTO 文件，用于校验和规范接口请求参数和响应数据。

dto/get-routes.dto.ts：

import { IsOptional, IsString, IsArray, IsNumber, IsDateString } from 'class-validator';

export class GetRoutesDto {
  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  attraction_ids?: string[];

  @IsOptional()
  @IsDateString()
  start_time?: string;

  @IsOptional()
  @IsDateString()
  end_time?: string;

  @IsOptional()
  @IsNumber()
  distance?: number;
}

dto/route-response.dto.ts：

export class RouteResponseDto {
  code: number;
  msg: string;
  data: any;
}

创建 Controller

routes.controller.ts：

import { Controller, Get, Param, Query } from '@nestjs/common';
import { RoutesService } from './routes.service';
import { GetRoutesDto } from './dto/get-routes.dto';
import { RouteResponseDto } from './dto/route-response.dto';

@Controller('api/routes')
export class RoutesController {
  constructor(private readonly routesService: RoutesService) {}

  // 获取推荐的旅游路线列表
  @Get()
  async getRecommendedRoutes(@Query() query: GetRoutesDto): Promise<RouteResponseDto> {
    const routes = await this.routesService.getRecommendedRoutes(query);
    return { code: 1, msg: 'success', data: routes };
  }

  // 获取单条旅游路线的详细信息
  @Get(':id')
  async getRouteById(@Param('id') id: number): Promise<RouteResponseDto> {
    const route = await this.routesService.getRouteById(id);
    if (route) {
      return { code: 1, msg: 'success', data: route };
    } else {
      return { code: 0, msg: 'Route not found', data: null };
    }
  }
}

创建 Service

routes.service.ts：

import { Injectable } from '@nestjs/common';
import { GetRoutesDto } from './dto/get-routes.dto';

// 模拟数据
const routes = [
  {
    id: 1,
    name: '路线名称1',
    attraction_ids: [1, 2, 3],
    start_time: '2022-09-01',
    end_time: '2022-09-05',
    distance: 50,
  },
  {
    id: 2,
    name: '路线名称2',
    attraction_ids: [1, 2, 3],
    start_time: '2022-09-01',
    end_time: '2022-09-05',
    distance: 50,
  },
];

@Injectable()
export class RoutesService {
  // 获取推荐的旅游路线列表
  getRecommendedRoutes(query: GetRoutesDto) {
    // 在这里根据查询参数进行过滤
    let filteredRoutes = routes;

    if (query.attraction_ids) {
      filteredRoutes = filteredRoutes.filter(route =>
        query.attraction_ids.every(id => route.attraction_ids.includes(Number(id))),
      );
    }

    if (query.start_time) {
      filteredRoutes = filteredRoutes.filter(route => route.start_time >= query.start_time);
    }

    if (query.end_time) {
      filteredRoutes = filteredRoutes.filter(route => route.end_time <= query.end_time);
    }

    if (query.distance) {
      filteredRoutes = filteredRoutes.filter(route => route.distance <= query.distance);
    }

    return filteredRoutes;
  }

  // 获取单条旅游路线的详细信息
  getRouteById(id: number) {
    return routes.find(route => route.id === id);
  }
}

Module 配置

routes.module.ts：

import { Module } from '@nestjs/common';
import { RoutesController } from './routes.controller';
import { RoutesService } from './routes.service';

@Module({
  controllers: [RoutesController],
  providers: [RoutesService],
})
export class RoutesModule {}
App Module 注册

在 app.module.ts 中注册 RoutesModule。

app.module.ts：

import { Module } from '@nestjs/common';
import { RoutesModule } from './routes/routes.module';

@Module({
  imports: [RoutesModule],
})
export class AppModule {}

票务模块

4.1 获取景点的票务信息
4.1.1 基本信息
  • 请求路径：/api/tickets
  • 请求方式：GET
  • 接口描述：获取景点的票务信息，包括票价、开放时间、是否有优惠等。
4.1.2 请求参数
  • 参数格式：queryString
  • 参数说明：
    • attraction_ids: 景点ID列表，多个ID用逗号分隔
4.1.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
4.1.4 请求数据样例

复制

/api/tickets?attraction_ids=1,2,3
4.1.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "attraction_id": 1,
      "ticket_type": "成人票",
      "price": 100.00,
      "open_time": "09:00-18:00",
      "discount": true
    },
    {
      "id": 2,
      "attraction_id": 2,
      "ticket_type": "儿童票",
      "price": 50.00,
      "open_time": "09:00-18:00",
      "discount": false
    },
    {
      "id": 3,
      "attraction_id": 3,
      "ticket_type": "学生票",
      "price": 80.00,
      "open_time": "09:00-18:00",
      "discount": true
    }
  ]
}
4.2 获取单个景点的票务详细信息
4.2.1 基本信息
  • 请求路径：/api/tickets/{id}
  • 请求方式：GET
  • 接口描述：获取单个景点的票务详细信息。
4.2.2 请求参数
  • 参数格式：路径参数
  • 参数说明：
    • id: 票务ID
4.2.3 响应数据
  • 参数格式：application/json
  • 参数说明：
    • code: 响应码，1 代表成功，0 代表失败
    • msg: 提示信息
    • data: 返回的数据
4.2.4 请求数据样例

复制

/api/tickets/1
4.2.5 响应数据样例

json

复制

{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "attraction_id": 1,
    "ticket_type": "成人票",
    "price": 100.00,
    "open_time": "09:00-18:00",
    "discount": true
  }
}

5. 导航与地图模块

5.1 地图和位置

5.1.1 基本信息

请求路径：/api/maps/{location}

请求方式：GET

接口描述：该接口用于获取指定景点或路线的地图位置，并提供路线导航。

5.1.2 请求参数
参数名类型是否必须备注
locationstring必须景点名称或路线ID

请求参数样例：

bash


复制代码
/api/maps/GreatWall
5.1.3 响应数据

参数格式：application/json

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据
|- locationstring非必须景点位置的描述
|- routestring非必须提供的路线导航信息
|- mapUrlstring非必须地图的链接

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "location": "Great Wall, Beijing, China",
    "route": "Start from Beijing, head towards the north for 30 km",
    "mapUrl": "https://maps.example.com/GreatWall"
  }
}

5.2 当前位置

5.2.1 基本信息

请求路径：/api/location/current

请求方式：GET

接口描述：该接口用于获取用户当前的位置，位置数据来源于腾讯地图。

5.2.2 请求参数

无

5.2.3 响应数据

参数格式：application/json

参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject非必须返回的数据
|- latitudenumber非必须当前纬度
|- longitudenumber非必须当前经度

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "latitude": 39.9042,
    "longitude": 116.4074
  }
}

6. 活动与促销模块

6.1 获取活动信息

6.1.1 获取景点附近或景点本身的活动信息

请求路径：GET /api/events
请求方式：GET
接口描述：获取景点附近或指定景点的活动信息，如节庆活动、演出等。

6.1.2 请求参数
参数名类型是否必须备注
locationstring可选景点名称，若不指定，获取全城的活动。
radiusnumber可选半径，单位米，指定获取某个范围内的活动，默认为1000米。
typestring可选活动类型，如“节庆”、“演出”等，默认获取所有活动类型。
startDatestring可选活动开始日期，格式为YYYY-MM-DD，用于筛选活动。
endDatestring可选活动结束日期，格式为YYYY-MM-DD，用于筛选活动。
6.1.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataarray必须活动信息列表
|- idstring必须活动ID
|- namestring必须活动名称
|- typestring必须活动类型
|- startDatestring必须活动开始日期，格式为YYYY-MM-DD
|- endDatestring必须活动结束日期，格式为YYYY-MM-DD
|- locationstring必须活动地点
|- descriptionstring可选活动描述
|- imageUrlstring可选活动图片URL

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": "event_123",
      "name": "长城音乐节",
      "type": "演出",
      "startDate": "2024-11-15",
      "endDate": "2024-11-17",
      "location": "北京-长城",
      "description": "为期三天的音乐盛宴，现场有众多知名艺人参与。",
      "imageUrl": "https://example.com/event_123_image.jpg"
    },
    {
      "id": "event_124",
      "name": "北京春节庙会",
      "type": "节庆",
      "startDate": "2024-02-10",
      "endDate": "2024-02-17",
      "location": "北京-地坛公园",
      "description": "传统的春节庙会，丰富多彩的民间艺术和手工艺展示。",
      "imageUrl": "https://example.com/event_124_image.jpg"
    }
  ]
}

6.2 获取单个活动的详细信息

6.2.1 请求路径

请求路径：GET /api/events/{id}
请求方式：GET
接口描述：获取指定活动的详细信息。

6.2.2 请求参数
参数名类型是否必须备注
idstring必须活动ID

请求参数样例：

bash


复制代码
GET /api/events/event_123
6.2.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须活动详细信息
|- idstring必须活动ID
|- namestring必须活动名称
|- typestring必须活动类型
|- startDatestring必须活动开始日期
|- endDatestring必须活动结束日期
|- locationstring必须活动地点
|- descriptionstring必须活动详细描述
|- imageUrlstring可选活动图片URL
|- ticketsarray可选票务信息，如票价、购票链接等

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "id": "event_123",
    "name": "长城音乐节",
    "type": "演出",
    "startDate": "2024-11-15",
    "endDate": "2024-11-17",
    "location": "北京-长城",
    "description": "为期三天的音乐盛宴，现场有众多知名艺人参与。",
    "imageUrl": "https://example.com/event_123_image.jpg",
    "tickets": [
      {
        "type": "VIP",
        "price": 1000,
        "link": "https://example.com/tickets/vip"
      },
      {
        "type": "普通票",
        "price": 300,
        "link": "https://example.com/tickets/normal"
      }
    ]
  }
}

6.3 优惠券和促销

6.3.1 获取用户优惠券信息

请求路径：GET /api/coupons
请求方式：GET
接口描述：获取当前用户的优惠券信息，包括已领取、已过期和未使用的优惠券。

6.3.2 请求参数

无

6.3.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataarray必须优惠券信息列表
|- idstring必须优惠券ID
|- discountnumber必须优惠券折扣，如10表示10%的折扣
|- typestring必须优惠券类型，如“满减”、“折扣”
|- validUntilstring必须有效期，格式为YYYY-MM-DD

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": "coupon_123",
      "discount": 10,
      "type": "折扣",
      "validUntil": "2024-12-31"
    },
    {
      "id": "coupon_124",
      "discount": 50,
      "type": "满减",
      "validUntil": "2024-11-30"
    }
  ]
}
6.3.2 用户兑换优惠券

请求路径：POST /api/coupons/redeem
请求方式：POST
接口描述：用户兑换优惠券，需传入优惠券ID进行兑换。

6.3.3 请求参数
参数名类型是否必须备注
couponIdstring必须要兑换的优惠券ID

请求体示例：

json复制代码{
  "couponId": "coupon_123"
}
6.3.4 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "兑换成功"
}

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "Spring Festival at Great Wall",
    "description": "Join us to celebrate the Spring Festival at the iconic Great Wall of China with traditional performances and food.",
    "startTime": "2024-02-01T10:00:00",
    "endTime": "2024-02-01T18:00:00",
    "location": "Great Wall, Beijing"
  }
}

7. 数据统计与分析模块

7.1 景点流量统计

7.1.1 获取景点的访问量、评分统计

请求路径：GET /api/stats/attractions/{id}
请求方式：GET
接口描述：获取指定景点的访问量、评分统计等信息，帮助分析景点的受欢迎程度。

7.1.2 请求参数
参数名类型是否必须备注
idstring必须景点ID（唯一标识符）

请求路径示例：

bash


复制代码
GET /api/stats/attractions/attraction_123
7.1.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须景点流量和评分统计数据
|- visitCountnumber必须景点的访问总量
|- avgRatingnumber必须景点的平均评分（1-5）
|- reviewsCountnumber必须用户评分的总数
|- peakTimestring可选访问量最高的时间段（如“周末”）
|- ratingBreakdownobject可选各个评分段的分布（如：5星、4星等）

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "visitCount": 1200,
    "avgRating": 4.5,
    "reviewsCount": 350,
    "peakTime": "周末",
    "ratingBreakdown": {
      "5stars": 200,
      "4stars": 120,
      "3stars": 30,
      "2stars": 10,
      "1star": 5
    }
  }
}

7.2 用户行为数据

7.2.1 分析用户行为，如最常访问的景点、路线、时间等

请求路径：GET /api/stats/users
请求方式：GET
接口描述：获取用户行为分析数据，帮助了解用户兴趣、活动习惯等。

7.2.2 请求参数
参数名类型是否必须备注
userIdstring可选用户ID，如果未传，则返回所有用户的行为数据
startDatestring可选数据分析的开始日期，格式为YYYY-MM-DD
endDatestring可选数据分析的结束日期，格式为YYYY-MM-DD

请求路径示例：

bash


复制代码
GET /api/stats/users?userId=user_123&startDate=2024-01-01&endDate=2024-11-01
7.2.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须用户行为数据
|- mostVisitedAttractionsarray必须用户最常访问的景点列表
|- mostVisitedRoutesarray可选用户最常使用的游览路线
|- visitTimesobject可选用户的访问时间统计（如：访问频率等）

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "success",
  "data": {
    "mostVisitedAttractions": [
      {
        "attractionId": "attraction_123",
        "attractionName": "长城",
        "visitCount": 50
      },
      {
        "attractionId": "attraction_124",
        "attractionName": "故宫博物院",
        "visitCount": 45
      }
    ],
    "mostVisitedRoutes": [
      {
        "routeId": "route_1",
        "routeName": "长城-故宫一日游",
        "visitCount": 30
      }
    ],
    "visitTimes": {
      "weekdays": "40%",
      "weekends": "60%"
    }
  }
}

8. 后台管理模块

8.1 管理员登录

8.1.1 请求路径

请求路径：POST /api/admin/login
请求方式：POST
接口描述：管理员登录，获取权限信息。

8.1.2 请求参数
参数名类型是否必须备注
usernamestring必须管理员的用户名
passwordstring必须管理员的密码

请求体示例：

json复制代码{
  "username": "admin",
  "password": "admin123"
}
8.1.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须登录成功后的管理员权限信息
|- tokenstring必须用于后续请求的认证Token

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "登录成功",
  "data": {
    "token": "abcdef1234567890"
  }
}

8.2 景点管理

8.2.1 添加或更新景点信息

请求路径：POST /api/admin/attractions
请求方式：POST
接口描述：管理员添加或更新景点信息。

8.2.2 请求参数
参数名类型是否必须备注
namestring必须景点名称
locationstring必须景点所在的地理位置（城市、区县等）
descriptionstring可选景点描述
imageUrlstring可选景点的图片URL
coordinatesobject可选景点的经纬度信息
|- latnumber可选纬度
|- lonnumber可选经度

请求体示例：

json复制代码{
  "name": "长城",
  "location": "北京",
  "description": "中国著名的历史遗址。",
  "imageUrl": "https://example.com/longwall.jpg",
  "coordinates": {
    "lat": 40.4319,
    "lon": 116.5704
  }
}
8.2.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须操作成功后的景点信息

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "景点添加成功",
  "data": {
    "id": "attraction_123",
    "name": "长城",
    "location": "北京",
    "description": "中国著名的历史遗址。",
    "imageUrl": "https://example.com/longwall.jpg",
    "coordinates": {
      "lat": 40.4319,
      "lon": 116.5704
    }
  }
}
8.2.4 删除景点

请求路径：DELETE /api/admin/attractions/{id}
请求方式：DELETE
接口描述：管理员删除指定的景点信息。

8.2.5 请求参数
参数名类型是否必须备注
idstring必须景点ID（唯一标识符）

请求路径示例：

bash


复制代码
DELETE /api/admin/attractions/attraction_123
8.2.6
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject可选删除操作的结果信息

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "景点删除成功",
  "data": {
    "id": "attraction_123",
    "name": "长城"
  }
}

8.3 订单管理

8.3.1 查看所有用户订单

请求路径：GET /api/admin/orders
请求方式：GET
接口描述：管理员查看所有用户订单，支持查询、修改订单状态等操作。

8.3.2 请求参数
参数名类型是否必须备注
statusstring可选订单状态，支持all（所有）、pending（待付款）、completed（已完成）、canceled（已取消）
startDatestring可选查询的开始日期，格式为YYYY-MM-DD
endDatestring可选查询的结束日期，格式为YYYY-MM-DD
userIdstring可选用户ID（查询指定用户的订单）

请求路径示例：

bash


复制代码
GET /api/admin/orders?status=pending&startDate=2024-01-01&endDate=2024-11-01
8.3.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataarray必须订单列表
|- orderIdstring必须订单ID
|- userIdstring必须用户ID
|- attractionIdstring必须景点ID
|- orderStatusstring必须订单状态（如pending、completed、canceled）
|- orderDatestring必须订单创建日期，格式为YYYY-MM-DD

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "查询成功",
  "data": [
    {
      "orderId": "order_123",
      "userId": "user_123",
      "attractionId": "attraction_123",
      "orderStatus": "pending",
      "orderDate": "2024-10-01"
    },
    {
      "orderId": "order_124",
      "userId": "user_124",
      "attractionId": "attraction_124",
      "orderStatus": "completed",
      "orderDate": "2024-10-02"
    }
  ]
}
8.3.4 修改订单状态

请求路径：PUT /api/admin/orders/{orderId}
请求方式：PUT
接口描述：管理员修改指定订单的状态。

8.3.5 请求参数
参数名类型是否必须备注
orderStatusstring必须订单状态（pending、completed、canceled）

请求路径示例：

bash


复制代码
PUT /api/admin/orders/order_123

请求体示例：

json复制代码{
  "orderStatus": "completed"
}
8.3.6 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject必须修改后的订单信息

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "订单状态更新成功",
  "data": {
    "orderId": "order_123",
    "orderStatus": "completed"
  }
}

9. 消息通知模块

9.1 发送推送通知

9.1.1 请求路径

请求路径：POST /api/notifications/send
请求方式：POST
接口描述：向用户发送推送通知，通知内容可以是活动促销、景点更新等信息。

9.1.2 请求参数
参数名类型是否必须备注
userIdstring必须用户ID
titlestring必须通知标题
messagestring必须通知内容
typestring可选通知类型（如promotion、update）
urlstring可选需要跳转的URL地址

请求体示例：

json复制代码{
  "userId": "user_123",
  "title": "特价促销活动",
  "message": "景点门票现有折扣，快来抢购！",
  "type": "promotion",
  "url": "https://example.com/promotion"
}
9.1.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataobject可选发送的通知详情

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "通知发送成功",
  "data": {
    "notificationId": "notif_123",
    "userId": "user_123",
    "title": "特价促销活动",
    "message": "景点门票现有折扣，快来抢购！",
    "url": "https://example.com/promotion"
  }
}

9.2 系统通知

9.2.1 获取用户的系统通知

请求路径：GET /api/notifications
请求方式：GET
接口描述：获取指定用户的所有系统通知，通常是系统更新、维护等重要消息。

9.2.2 请求参数
参数名类型是否必须备注
userIdstring必须用户ID

请求路径示例：

bash


复制代码
GET /api/notifications?userId=user_123
9.2.3 响应数据
参数名类型是否必须备注
codenumber必须响应码，1 代表成功，0 代表失败
msgstring非必须提示信息
dataarray必须用户的系统通知列表
|- notificationIdstring必须通知ID
|- titlestring必须通知标题
|- messagestring必须通知内容
|- timestampstring必须通知时间，格式为YYYY-MM-DD HH:mm:ss

响应数据样例：

json复制代码{
  "code": 1,
  "msg": "查询成功",
  "data": [
    {
      "notificationId": "notif_123",
      "title": "系统更新",
      "message": "我们的服务将在今晚进行维护，预计10小时。",
      "timestamp": "2024-11-10 22:00:00"
    },
    {
      "notificationId": "notif_124",
      "title": "新的活动上线",
      "message": "查看我们的最新节庆活动，优惠券大放送。",
      "timestamp": "2024-11-11 10:00:00"
    }
  ]
}

原文地址：https://blog.csdn.net/XiugongHao/article/details/143730626

免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！

相关文章

自学内容网
Copyright © 2015-2024