PHP API开发：通用响应格式与状态码规范笔记

为了确保接口的返回格式统一且易于维护，我整理了一些通用的响应格式和状态码规范。这些笔记不仅帮助我在开发过程中保持一致性，也便于后续的调试和维护。

设置响应头

每个API的响应头可以统一设置如下，以确保跨域访问和正确的内容类型：

	
	

		
		

			
		

		

			
		

		

			
		

	

	

		
		

			
			

				header('Access-Control-Allow-Origin:*'); // 允许所有来源访问
			

		

		

			
			

				header('Access-Control-Allow-Method:POST,GET'); // 允许的访问方法
			

		

		

			
			

				header('Content-type: application/json;charset=utf-8'); // 设置响应头编码为UTF-8
			

		

	

JSON格式化

为了确保JSON数据的可读性和一致性，可以使用 json_encode 的以下选项：

	
	

		
		

			
		

		

			
		

		

			
		

	

	

		
		

			
			

				$options = JSON_NUMERIC_CHECK | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;
			

		

		

			
			

				echo json_encode($response, $options);
			

		

	

• JSON_NUMERIC_CHECK：将所有数字字符串转换为数字。
• JSON_PRETTY_PRINT：格式化JSON，便于阅读。
• JSON_UNESCAPED_UNICODE：不对中文字符进行转义。
• JSON_UNESCAPED_SLASHES：不对斜杠进行转义。

常见HTTP状态码

在处理HTTP请求时，以下是一些常见的状态码及其说明：

• 200：请求成功，表示服务器成功处理了请求。
• 400：请求错误，比如参数错误或请求格式不正确。
• 401：未授权，通常指用户未提供有效的身份验证信息。
• 403：禁止访问，用户没有权限访问该资源。
• 404：资源未找到，表示请求的API端点不存在。

BaseResponse 响应格式

为了使API响应格式保持一致，可以使用一个通用的 BaseResponse 函数：

	
	

		
		

			
		

		

			
		

		

			
		

	

	

		
		

			
			

				function BaseResponse($code, $message, $data = []) {
			

		

		

			
			

				 $response = [
			

		

		

			
			

				 'code' => $code,
			

		

		

			
			

				 'message' => $message,
			

		

		

			
			

				 'data' => $data
			

		

		

			
			

				 ];
			

		

		

			
			

				 
			

		

		

			
			

				  // 设置响应头
			

		

		

			
			

				 header('Access-Control-Allow-Origin:*');
			

		

		

			
			

				 header('Access-Control-Allow-Method:POST,GET');
			

		

		

			
			

				 header('Content-type: application/json;charset=utf-8');
			

		

		

			
			

				 
			

		

		

			
			

				  // 输出JSON
			

		

		

			
			

				 echo json_encode($response, JSON_NUMERIC_CHECK | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
			

		

		

			
			

				 exit();
			

		

		

			
			

				}
			

		

	

接口文档规范

编写接口文档时，可以按照以下结构进行描述：

1. 接口标题：简要描述接口的功能。
2. 接口描述：详细说明接口的作用。
3. 请求方法：例如 POST 或 GET。
4. 请求URL：接口的访问地址。
5. 请求参数：
   • 参数名
   • 类型
   • 是否必填
   • 说明
6. 返回参数：
   • 参数名
   • 类型
   • 说明

示例：用户登录API

接口标题：用户登录

接口描述：用于用户登录并获取Token。

请求方法：POST

请求URL：/api/v1/login

请求参数：

返回参数：

请求示例：

	
	

		
		

			
		

		

			
		

		

			
		

	

	

		
		

			
			

				{
			

		

		

			
			

				 "username": "user123",
			

		

		

			
			

				 "password": "password123"
			

		

		

			
			

				}
			

		

	

返回示例：

	
	

		
		

			
		

		

			
		

		

			
		

	

	

		
		

			
			

				{
			

		

		

			
			

				 "code": 200,
			

		

		

			
			

				 "message": "登录成功",
			

		

		

			
			

				 "data": {
			

		

		

			
			

				 "token": "abcdefg123456"
			

		

		

			
			

				 }
			

		

		

			
			

				}
			

		

	

最后

这些笔记是我在API开发过程中总结出的经验，希望能对其他开发者有所帮助。通过统一的响应格式和规范的接口文档，可以有效提升API的可维护性和一致性。这些内容虽然是个人观点，但我相信在实际开发中也会带来不少便利。如果你有不同的见解或改进建议，欢迎分享！

转自https://www.ahfi.cn/770.html