Debian 上基于 JSP 的 API 接口设计指南
一 环境与运行时搭建
- 安装 OpenJDK 11：sudo apt update && sudo apt install openjdk-11-jdk。
- 安装 Tomcat 9（两种常用方式）：
- 包管理：sudo apt install tomcat9（便于 systemd 管理、自动部署到 /var/lib/tomcat9/webapps）。
- 手动部署：下载并解压 Tomcat 至 /opt/tomcat，创建专用用户与权限，编写 systemd 服务（设置 JAVA_HOME、CATALINA_HOME、CATALINA_BASE 等），使用 sudo systemctl start|enable tomcat 管理。
- 验证：访问 http://服务器IP:8080，看到 Tomcat 欢迎页即表示运行正常。
- 部署应用：将 WAR 包复制到 Tomcat 的 webapps 目录（如 /var/lib/tomcat9/webapps/ROOT.war 或自定义目录），容器会自动解压部署。
二 API 设计规范与端点设计
- 资源与 URI：以资源为中心设计，例如 /api/v1/users、/api/v1/users/{id}。
- HTTP 动词语义：
- GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除。
- 状态码：
- 200 成功、201 已创建、204 无内容、400 请求错误、401 未认证、403 未授权、404 未找到、429 限流、500 服务器错误。
- 数据格式与版本：统一使用 JSON，请求/响应统一 Content-Type: application/json；通过 /api/v1/ 路径进行版本管理。
- 统一响应结构（建议）：
- 成功：{ “code”: 0, “message”: “OK”, “data”: { … } }
- 失败：{ “code”: 10001, “message”: “Invalid parameter”, “details”: […] }
- 分页与过滤：GET /api/v1/users?page=1&size=20&sort=name,asc&status=ACTIVE。
- 错误码规范：业务域前缀 + 序号，例如 USER_001 表示用户模块错误。
三 在 JSP/Servlet 中落地 REST 接口
- 方案一 轻量 Servlet + JSON：用 HttpServlet 处理 doGet/doPost/doPut/doDelete，手动序列化 JSON（如 jakarta.json 或 Jackson/Gson），设置状态码与响应头。适合简单接口或遗留系统渐进式改造。
- 方案二 JAX-RS（推荐）：使用 Jersey（JAX-RS 参考实现）快速构建 REST。
- 依赖：将 jersey-container-servlet 等 JAR 放入 WEB-INF/lib。
- 应用类：
- @ApplicationPath(“/api”) public class MyApplication extends Application { }
- 资源类：
- @Path(“/users”) public class UserResource {
- @GET @Produces(MediaType.APPLICATION_JSON) public Response list() { … }
- @POST @Consumes(MediaType.APPLICATION_JSON) public Response create(UserDto dto) { … }
- @GET @Path(“{id}”) public Response get(@PathParam(“id”) Long id) { … }
- @PUT @Path(“{id}”) public Response update(@PathParam(“id”) Long id, UserDto dto) { … }
- @DELETE @Path(“{id}”) public Response delete(@PathParam(“id”) Long id) { … }
}
- web.xml 注册 Jersey Servlet（或使用 Servlet 3.0+ 自动扫描）：
- Jerseyorg.glassfish.jersey.servlet.ServletContainer
javax.ws.rs.Applicationcom.example.MyApplication
1
- Jersey/api/*
- 安全与输入校验：在入口统一做 认证/鉴权（如 JWT）、参数校验（Bean Validation）、异常映射（统一 JSON 错误返回），避免把业务逻辑写在 JSP 页面中（JSP 更适合作为视图或错误页）。
四 安全与运维实践
- 传输与证书：全站启用 HTTPS（反向代理或 Tomcat 配置 TLS），禁用明文端口。
- 认证与授权：优先 JWT/OAuth 2.0；敏感接口使用 短时效 Token + 刷新 Token，配合 RBAC 或 ABAC。
- 限流与防护：对相同 IP/Token/用户 限流（如令牌桶/漏桶），防 SQL 注入/XSS/CSRF，对上传做类型与大小限制。
- 日志与监控：记录 访问日志 与 业务日志（JSON 化便于检索），接入 Prometheus + Grafana 监控 JVM/HTTP/线程池，异常告警。
- 高可用：多实例 Tomcat + Nginx 负载均衡（HTTP/HTTPS），会话保持或 无状态 设计；健康检查与自动故障转移。
- 部署与回滚：WAR 包自动部署、蓝绿/金丝雀发布，回滚预案与 CI/CD。
五 文档、测试与交付
- 文档：使用 OpenAPI/Swagger 注解生成在线文档与调试页面，提供 在线示例 与 错误码字典。
- 测试：
- 单元/集成测试（如 JUnit + Mockito 对 Service/DAO 层）。
- 契约/端到端测试（Postman Collection/Newman 或自动化流水线）。
- 性能与安全测试（如 JMeter/Locust 做压测，检查 限流/鉴权 有效性）。
- 交付清单：版本化 API 文档、部署手册、回滚方案、健康检查脚本、指标与日志规范。