如何在同一API端点处理多个不同请求_技术教程

本文探讨了如何在同一个API端点下，通过引入查询字符串参数来区分和处理多个逻辑上独立的请求。通过在客户端`fetch`请求中添加`action`参数，并在服务器端使用`switch`语句进行路由，实现了对不同数据获取逻辑的有效分离与执行，确保了前后端交互的清晰与正确。

在构建Web应用程序时，我们经常会遇到需要从服务器获取多种类型数据的情况。有时，这些数据可能逻辑上相关，甚至共享同一个基础资源路径。然而，如果直接向同一个URL端点发起多个不带区分参数的请求，服务器将难以判断客户端的具体意图，从而可能导致数据混淆或处理错误。本教程将详细介绍如何通过在客户端请求中加入查询字符串参数，并在服务器端进行相应的逻辑判断，来实现在同一API端点下处理多个不同请求的方法。

1. 问题分析与现有实现

假设我们有一个API端点 http://server-npk-web-core/specialties，我们希望通过它获取两个不同的数据集：一个是专业列表（specialties），另一个是特定专业下的科目列表（subjectsSpecial）。

当前客户端（UI）代码示例：

async function getSpecialties(){
  let res = await fetch ('http://server-npk-web-core/specialties'); // 请求专业列表
  let specialties = await res.json();
  // ... 处理 specialties 数据
}

async function getSubjectsSpecial(){
  let res = await fetch ('http://server-npk-web-core/specialties'); // 请求特定专业科目
  let subjectsSpecial = await res.json();
  // ... 处理 subjectsSpecial 数据
}

当前服务器端（BLL - index.php 和 specialties.php）代码示例：

// index.php
if($method === 'GET'){
  if($type === 'subjects'){
    getSubjects($pdo);
  } elseif($type === 'specialties'){
    getSpecialties($pdo); // 可能会同时调用，导致输出混乱
    getSubjectsSpecial($pdo);
  }
}

// specialties.php (包含具体数据获取逻辑)
function getSpecialties($pdo){
  $specialties = 'SELECT * FROM `specialties`';
  $stmt = $pdo -> query($specialties);
  $specialtiesList = [];
  while ($special = $stmt->fetch()){
    $specialtiesList[] = $special;
  }
  echo json_encode($specialtiesList); // 输出JSON
}

function getSubjectsSpecial($pdo){
  $subjectsSpecial = 'SELECT `subjects`.`title` FROM `subjects` WHERE `id_specialties` = 2';
  $stmt = $pdo -> query($subjectsSpecial);
  $subjectsSpecialList = [];
  while ($subjectSpecial = $stmt->fetch()){
    $subjectsSpecialList[] = $subjectSpecial;
  }
  echo json_encode($subjectsSpecialList); // 输出JSON
}

从上述代码可以看出，客户端的两个 fetch 请求都指向完全相同的URL。在服务器端，index.php 在处理 type === 'specialties' 时，可能同时调用了 getSpecialties($pdo) 和 getSubjectsSpecial($pdo)。由于这两个函数都会直接 echo json_encode 输出JSON，这会导致响应体中包含两个独立的JSON字符串，从而形成一个无效的JSON响应，客户端将无法正确解析。

2. 解决方案：使用查询字符串参数进行路由

为了解决这个问题，我们需要在客户端请求中加入一个参数，以明确告知服务器端当前请求的具体意图。服务器端则根据这个参数来执行相应的业务逻辑。查询字符串参数（Query String Parameter）是实现这一目标的常用且有效的方法。

2.1 修改客户端 fetch 请求

在客户端的 fetch 请求中，我们可以通过添加 ?action=xxx 的形式来传递意图。

现在，getSpecialties 请求的URL是 http://server-npk-web-core/specialties?action=specialties，而 getSubjectsSpecial 请求的URL是 http://server-npk-web-core/specialties?action=subjectsspecial。服务器端可以通过检查 $_GET['action'] 的值来区分这两个请求。

2.2 修改服务器端 PHP 逻辑

在服务器端，我们需要检查 $_GET['action'] 参数，并根据其值使用 switch 语句来调用正确的函数。

 query($specialties);
      $specialtiesList = [];
      while ($special = $stmt->fetch(PDO::FETCH_ASSOC)){ // 使用PDO::FETCH_ASSOC获取关联数组
        $specialtiesList[] = $special;
      }
      header('Content-Type: application/json'); // 明确指定响应头为JSON
      echo json_encode($specialtiesList);
    }

    /**
     * 获取特定专业下的科目列表 (示例中 id_specialties = 2)
     * @param PDO $pdo 数据库连接对象
     */
    function getSubjectsSpecial($pdo){
      // 注意：实际应用中，id_specialties 应该从请求参数中获取，而不是硬编码
      $subjectsSpecial = 'SELECT `subjects`.`title` FROM `subjects` WHERE `id_specialties` = 2';
      $stmt = $pdo -> query($subjectsSpecial);
      $subjectsSpecialList = [];
      while ($subjectSpecial = $stmt->fetch(PDO::FETCH_ASSOC)){
        $subjectsSpecialList[] = $subjectSpecial;
      }
      header('Content-Type: application/json'); // 明确指定响应头为JSON
      echo json_encode($subjectsSpecialList);
    }

    // 核心路由逻辑
    if( !empty( $_GET['action'] ) ){
        switch( $_GET['action'] ){
            case 'specialties':
                getSpecialties($pdo);
            break;
            case 'subjectsspecial':
                getSubjectsSpecial( $pdo );
            break;
            default:
                // 处理未知 action 的情况，返回错误信息
                header('Content-Type: application/json');
                http_response_code(400); // Bad Request
                echo json_encode(['error' => 'Invalid action specified']);
            break;
        }
    } else {
        // 如果没有指定 action 参数，也可以定义一个默认行为，或返回错误
        header('Content-Type: application/json');
        http_response_code(400); // Bad Request
        echo json_encode(['error' => 'Action parameter is missing']);
    }
?>

注意事项：

header('Content-Type: application/json');: 在 echo json_encode() 之前添加此行非常重要，它告诉客户端响应体是JSON格式，有助于客户端正确解析。
错误处理: default 分支和 else 分支用于处理 action 参数无效或缺失的情况，返回适当的HTTP状态码（如 400 Bad Request）和错误信息，增强API的健壮性。
参数化查询: 在 getSubjectsSpecial 函数中，WHERE id_specialties = 2 是硬编码的。在实际应用中，id_specialties 应该作为另一个查询参数从客户端传递过来，并使用预处理语句（Prepared Statements）来防止SQL注入。例如：http://server-npk-web-core/specialties?action=subjectsspecial&specialty_id=2。

3. 总结与最佳实践

通过引入查询字符串参数，我们成功地在同一个API端点下实现了对多个不同请求的区分和处理。这种方法具有以下优点：

逻辑清晰: 服务器端能够明确知道客户端的意图，并执行相应的业务逻辑。
避免冲突: 解决了多个函数同时输出JSON导致响应体无效的问题。
统一入口: 对于逻辑上相关但数据类型不同的请求，可以保持一个统一的API入口点。

最佳实践建议：

RESTful API 设计: 尽管查询参数可以解决问题，但更符合RESTful原则的做法是为不同的资源或操作设计不同的URL路径。例如，GET /specialties 获取所有专业，GET /specialties/{id}/subjects 获取特定专业的科目。当资源路径不能完全区分时，再考虑使用查询参数。
参数校验: 对所有接收到的查询参数进行严格的校验，包括类型、格式和值的范围，以确保数据的有效性和安全性。
错误信息标准化: 提供清晰、一致的错误响应格式，包含错误代码和描述，方便客户端调试和处理。
安全性: 对于涉及到敏感数据的操作，始终使用HTTPS。对于数据库操作，务必使用预处理语句来防止SQL注入。
可扩展性: 当请求类型增多时，switch 语句可能会变得冗长。可以考虑更高级的路由机制或框架来管理API端点。

通过遵循这些原则和实践，您可以构建出更加健壮、可维护和易于理解的Web API。