Android + PHP 实战：用 OkHttp 对接 RESTful API 完整指南

在移动端开发中，Android 与服务端的数据交互是绕不开的核心环节。本文以一个完整的用户管理系统为例，手把手演示如何用 PHP 搭建 RESTful API，再用 Android 的 OkHttp + Retrofit 进行对接，覆盖从接口设计到安全鉴权的完整链路。

1. PHP 服务端：搭建 RESTful API

RESTful API 的核心约定是：用 HTTP 方法（GET/POST/PUT/DELETE）表达操作语义，用 URI 表达资源，用 JSON 传递数据，用 HTTP 状态码表达结果。

以用户模块为例，接口设计如下：

• GET /api/users：获取用户列表

• GET /api/users/{id}：获取单个用户

• POST /api/users：创建用户

• PUT /api/users/{id}：更新用户

• DELETE /api/users/{id}：删除用户

PHP 服务端核心实现：路由解析请求方法和路径，调用对应的 Controller 处理业务逻辑，统一返回 JSON 格式响应。响应结构约定为 {"code": 200, "message": "success", "data": {...}}，便于客户端统一处理。

数据库层使用 PDO 进行操作，支持参数绑定防止 SQL 注入。创建用户时对密码使用 password_hash() 加密存储，验证时使用 password_verify()，禁止明文存储密码。

2. JWT 鉴权：让 API 更安全

REST API 是无状态的，不能依赖 Session。推荐使用 JWT（JSON Web Token）进行鉴权：

• 登录：用户提交账号密码 → 服务端验证成功后签发 JWT Token → 客户端保存

• 请求：客户端每次请求在 Header 中携带 Authorization: Bearer {token}

• 验证：服务端解析并校验 Token 的签名和有效期

PHP 用 firebase/php-jwt 库生成和验证 Token，签名密钥需保存在环境变量中，不能写死在代码里。Token 建议设置 2 小时过期，配合 Refresh Token 机制实现无感刷新。

3. Android 端：OkHttp 封装 HTTP 请求

OkHttp 是 Android 最主流的 HTTP 客户端，支持连接池、拦截器、异步请求等特性。在 build.gradle 中添加依赖后，推荐封装一个单例的 ApiClient 类，统一管理：

• BaseUrl：统一 API 地址前缀

• 超时配置：connect/read/write timeout 各设置 30s

• 拦截器：全局添加 Authorization Header，记录请求日志

• 错误处理：统一拦截 HTTP 错误码，区分网络错误与业务错误

对于 GET 请求直接构建 URL + Request.Builder；POST/PUT 请求用 RequestBody.create() 传递 JSON body，注意 MediaType 设置为 application/json; charset=utf-8。

4. Retrofit 进阶：声明式接口调用

在 OkHttp 基础上，Retrofit 提供了更优雅的接口调用方式。通过注解定义接口，Retrofit 自动完成序列化、反序列化和请求组装：

• @GET("users/{id}")：GET 请求，路径参数用 @Path 注入

• @POST("users")：POST 请求，请求体用 @Body 传入

• @Header：添加请求头

• 配合 Gson 转换器自动将 JSON 转为 Kotlin/Java 数据类

在 Android 中推荐配合协程使用：suspend fun + viewModelScope.launch 在 IO 线程发请求，结果自动切换到主线程更新 UI，避免手写回调地狱。

5. 跨域与 HTTPS 配置

生产环境必须做好这两项配置：

• CORS：PHP 服务端设置响应头 Access-Control-Allow-Origin，限制允许的来源域名，避免通配符 *

• HTTPS：Android 9+ 默认禁止明文 HTTP 请求，必须配置 SSL 证书；调试阶段可在 network_security_config.xml 中临时允许 cleartext，但生产版本必须移除

• 证书固定（Certificate Pinning）：高安全性应用可在 OkHttp 中配置 CertificatePinner，防止中间人攻击

6. 常见问题与排查技巧

• Android 主线程网络请求报错：OkHttp 异步请求必须在子线程，使用 enqueue() 而非 execute()

• PHP 返回 500：开启 display_errors 或查看 error_log，常见原因是数据库连接失败或字段名拼写错误

• JSON 解析失败：检查 PHP 是否输出了额外内容（BOM、echo 调试语句），可用 ob_clean() 清空缓冲区

• Token 过期处理：Android 端捕获 401 响应，自动调用刷新接口获取新 Token 后重试原请求

• 接口调试：推荐用 Postman 先验证 API，再对接 Android 端，缩短排查链路

总结

Android + PHP 的全栈组合门槛低、生态成熟，适合个人项目和中小团队快速落地。核心要点：PHP 端严格遵循 REST 规范、做好鉴权与 SQL 防注入；Android 端统一封装 HTTP 客户端、做好异常处理和 HTTPS 配置。掌握这套组合，从功能开发到安全加固都能游刃有余。