后端如何写好一个接口

最新推荐文章于 2025-02-20 23:55:42 发布
最新推荐文章于 2025-02-20 23:55:42 发布
阅读量3.3k 收藏 34
点赞数 34
分类专栏： java 文章标签： java spring boot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_74943407/article/details/142796371
版权

目录

什么是接口

  • API接口 是一组规则和协议，允许不同的软件应用程序之间进行交互和通信。它定义了如何请求服务、数据格式、返回值以及错误处理等方面的规范

实现目标

要写好一个接口（API），不仅需要具备一定的技术技能，还需要考虑设计、健壮性和易用性。总结16大字：功能明确、设计合理、性能优化、易于维护。

操作步骤

编写接口的详细步骤

1.明确需求：

  • 确定接口的具体功能。例如：是创建用户、更新数据还是执行某种业务逻辑。
    理解接口输入输出的需求（需要接收哪些参数，返回什么数据）。

2.设计接口：

  • URL 路径设计：接口路径应简洁清晰，遵循 RESTful 风格，使用名词来代表资源。

  • 定义参数：

    • 路径参数：用来在 URL 中传递动态的资源 ID，例如 /users/{id}。

    • 查询参数：用于筛选、排序等功能，例如 /users?page=2&size=10。

    • 请求体参数：对于 POST、PUT、PUT、DELETE请求，通常需要一个请求体传递数据。

        GET：获取资源
  POST：创建资源
  PUT：更新资源
  DELETE：删除资源
  例如：GET /users（获取用户列表）、POST /users（创建用户）、GET /users/{id}（根据用户 ID 获取用户详细信息）。

  • 请求格式：如果接口需要接收数据，通常使用 JSON 格式传递请求体的数据。例如，登录接口的请求体可以包含用户名和密码。

3.校验输入参数：

  • 对客户端传入的参数进行校验，确保数据合法、格式正确。
    • 例如，检查用户名是否为空，密码是否符合安全要求。

4.业务逻辑处理：

  • 在 Service 层 实现核心业务逻辑，例如注册用户、检查用户名是否重复、密码加密等。
  • DAO 层（数据访问层）负责与数据库交互，完成数据存储、更新、查询等操作。

5.错误处理：

  • 根据业务逻辑处理可能的错误场景，并返回合适的错误码和错误信息。
    • 例如，用户不存在、数据不合法、权限不足等。

6.返回响应：

  • 统一格式的响应体返回结果数据，包含 code（状态码）、message（说明信息）、data（具体数据，可能为空）。
  •   200 OK：请求成功。
  201 Created：资源成功创建。
  400 Bad Request：请求参数有误。
  401 Unauthorized：认证失败，用户未登录或凭证无效。
  403 Forbidden：用户无权限访问资源。
  404 Not Found：请求的资源不存在。
  500 Internal Server Error：服务器内部错误。
  • 示例响应：
{
  "code": 200,
  "message": "Registration successful",
  "data": null
}

7.测试接口：

  • 使用工具（如 Postman）或自动化测试脚本，测试接口的各类功能，确保其正常工作。
  • 包含正向测试（正常输入），和负向测试（异常输入，如缺少参数、参数格式错误等）。

8.编写文档：

  • 使用文档工具（如 Swagger）编写接口文档，描述请求路径、方法、参数说明、示例请求和响应。
  • 让其他开发者或前端人员了解如何使用接口。**

示例:（用户注册接口）

  1. Controller 层：负责接收客户端请求，调用 Service 层处理逻辑，返回响应结果。
// Controller 层，负责处理 HTTP 请求
@RestController // 标记为一个 RESTful 控制器
@RequestMapping("/api") // 为所有接口统一设置一个路径前缀
public class UserController {

    @Autowired // 自动注入 UserService
    private UserService userService;

    /**
     * 用户注册接口
     * @param userDTO 从请求体中接收的用户信息
     * @return 注册结果
     */
    @PostMapping("/register") // 映射 HTTP POST 请求到 /api/register
    public Result register(@RequestBody UserDTO userDTO) {
        // 校验输入参数是否合法
        if (userDTO.getUsername() == null || userDTO.getPassword() == null) {
            // 如果用户名或密码为空，返回 400 错误
            return Result.error(400, "用户名或密码不能为空");
        }

        // 调用 Service 层处理业务逻辑
        boolean isRegistered = userService.register(userDTO);

        // 根据业务逻辑结果返回响应
        return isRegistered ? Result.success("注册成功") : Result.error(409, "用户名已存在");
    }
}
  • @RestController：声明这是一个控制器，返回的结果会自动转换为 JSON。
  • @RequestBody：用于将请求体中的 JSON 数据自动绑定到 UserDTO 对象。
  • userService.register(userDTO)：调用 Service 层注册逻辑。
  1. Service 层：定义业务逻辑接口，提供服务调用的入口。
// Service 层接口，定义注册相关的业务逻辑
public interface UserService {

    /**
     * 用户注册业务逻辑接口
     * @param userDTO 包含用户信息的对象
     * @return 是否注册成功
     */
    boolean register(UserDTO userDTO);
}
  • boolean register(UserDTO userDTO)：定义一个注册方法，返回 true 表示成功，false 表示失败。
  1. ServiceImpl 层：实现 Service 层接口，编写具体的业务逻辑。
// Service 层实现类，具体实现业务逻辑
@Service // 标记为 Spring 的 Service 组件，表示这是一个服务
public class UserServiceImpl implements UserService {

    @Autowired // 自动注入 Mapper 层，用于数据库操作
    private UserMapper userMapper;

    /**
     * 实现用户注册逻辑
     * @param userDTO 包含用户信息的对象
     * @return 是否注册成功
     */
    @Override // 标注这是接口方法的实现
    public boolean register(UserDTO userDTO) {
        // 调用 Mapper 层，查询用户名是否已存在
        User existingUser = userMapper.findByUsername(userDTO.getUsername());
        if (existingUser != null) {
            // 如果用户已存在，返回 false 表示注册失败
            return false;
        }

        // 如果用户名不存在，调用 Mapper 层保存用户信息
        userMapper.save(userDTO);
        return true; // 返回 true 表示注册成功
    }
}
  • @Service：声明这是一个业务服务组件。
  • userMapper.findByUsername(userDTO.getUsername())：检查用户名是否已存在。
  • userMapper.save(userDTO)：如果用户名不存在，保存新用户信息。
  1. Mapper 层：负责与数据库交互，执行 SQL 查询和插入操作。
// Mapper 层，负责与数据库交互
@Mapper // 标记为 MyBatis 的 Mapper，自动生成实现类
public interface UserMapper {

    /**
     * 根据用户名查询用户是否存在
     * @param username 要查询的用户名
     * @return 如果存在则返回用户对象，否则返回 null
     */
    @Select("SELECT * FROM users WHERE username = #{username}") // 使用 MyBatis 注解编写 SQL 查询语句
    User findByUsername(String username);

    /**
     * 保存用户信息到数据库
     * @param userDTO 包含用户信息的对象
     */
    @Insert("INSERT INTO users (username, password, email) VALUES (#{username}, #{password}, #{email})") // 插入用户信息
    void save(UserDTO userDTO);
}
  • @Mapper：表示这是 MyBatis 的 Mapper 接口，Spring 会自动实现接口的实现类。
  • @Select 和 @Insert：分别用于查询和插入 SQL 语句。
  • findByUsername：通过用户名查询用户信息。
  • save：将新用户信息插入到数据库中。
  1. DTO（数据传输对象）：用于封装请求体中的数据。
// 数据传输对象，用于封装请求数据
@NoArgsConstructor//生成无参构造函数
@AllArgsConstructor//生成全参构造函数
@Data // 使用 @Data 注解自动生成 getter 和 setter 方法
public class UserDTO {
    private String username; // 用户名
    private String password; // 密码
    private String email;    // 邮箱
}
  1. Result（统一响应对象）：用于统一处理返回的响应结果。
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data // 自动生成 getter、setter、toString、equals 和 hashCode 方法
@NoArgsConstructor // 生成无参构造函数
@AllArgsConstructor // 生成全参构造函数
public class Result {
    private Integer code; // 响应码，1 代表成功; 0 代表失败
    private String msg;   // 响应信息 描述字符串
    private Object data;  // 返回的数据

    // 增删改 成功响应
    public static Result success() {
        return new Result(1, "success", null);
    }

    // 查询 成功响应
    public static Result success(Object data) {
        return new Result(1, "success", data);
    }

    // 失败响应
    public static Result error(String msg) {
        return new Result(0, msg, null);
    }
}

  • @Data: 这个注解会为所有字段生成 getter 和 setter 方法，toString() 方法，以及 equals() 和 hashCode() 方法。这使得这个类更简洁，同时提供了常用的功能。

  • @NoArgsConstructor: 生成一个无参构造函数，可以方便地创建 Result 对象。

  • @AllArgsConstructor: 生成一个全参构造函数，可以通过提供所有字段的值来创建 Result 对象。

  • 响应方法:

    • public static Result success(): 创建一个表示成功但不带任何数据的响应。
    • public static Result success(Object data): 创建一个表示成功并包含数据的响应。
    • public static Result error(String msg): 创建一个表示失败并包含错误信息的响应。

架构

  • Controller 层：处理 HTTP 请求，将请求体数据转换为对象，并调用 Service 层执行业务逻辑。
  • Service 层：定义业务逻辑接口，由 ServiceImpl 实现实际的业务处理。
  • ServiceImpl 层：通过调用 Mapper 层来执行数据库操作，实现具体的业务逻辑。
    Mapper 层：负责执行数据库操作，查询和保存数据。
  • DTO：封装请求数据，使得数据传输格式统一。
  • Result：用于统一 API 响应结构，便于前端处理返回数据。

通过这个结构，接口开发的逻辑清晰，每一层都各司其职，降低了代码耦合性，同时提高了代码的可读性和维护性。

调用关系

  • UserController (Controller) 调用 UserService (Service) 来处理业务逻辑。
  • UserService (Service) 是 UserServiceImpl (ServiceImpl) 的接口。
  • UserServiceImpl (ServiceImpl) 调用 UserMapper (Mapper) 进行数据库操作。
  • UserMapper (Mapper) 使用 UserDTO (DTO) 进行数据传输。
  • UserController (Controller) 返回 Result (Response) 对象，表示接口的响应结果。
    在这里插入图片描述
REST架构中，后端如何写接口及单元测试
羊同学
08-17 3667
后端举例，接口测试在实际应用中编写最容易，编写速度最快的就是整合测试。 1）整合测试测试接口逻辑与数据库ORM等多个功能，可以用到web开发框架(如Django、Flask等)自带的测试客户端和测试类(如Django的TestCase)。 2）不管是接口测试用例还是单元测试用例，其主要测试方向都是集中测试指定的接口或函数功能上”做什么”。如，对于REST型接口而言，主要测试的方面包括：传入有效...
put请求方式参数如何传_后端开发之如何写接口设计文档
weixin_39608118的博客
12-03 6398
“高质量的规范文档是一个优秀设计系统的代表物”“你这接口文档，谁能看懂啊，写的都是啥，能调通才怪呢！浪费我时间”“你到底会不会看文档啊，调用方式，参数都给你写的很清楚了，年轻人，还需继续努力啊！”"你...""我怎么..."前端:后端,我要分手气氛很不好，大家都看到了吧，现在项目都是前后端分...
后端接口文档例子 word
03-18
word版接口文档
花10分钟写个漂亮的后端API接口模板！
田维常
07-29 1434
你好，我是田哥在这微服务架构盛行的黄金时段，加上越来越多的前后端分离，导致后端API接口规范变得越来越重要了。比如：统一返回参数形式、统一返回码、统一异常处理、集成swagger等。目的主要是规范后端项目代码，以及便于前端沟通联通以及问题的排查。本文内容：统一返回参数形式目前主流的返回参数形式：{ "code":200000, "message":"成功", "data":{ ...
零基础也能懂的 API 接口文档编写指南，适合开发人员
weixin_45017726的博客
02-13 3592
文档概述是 API 文档的"第一印象"，它就像一本书的封面和目录。这部分内容帮助用户快速了解：这个 API 是做什么用的API 的当前版本和更新状态使用这个 API 需要知道的基本信息# 天气查询API文档版本：v1.0最后更新：2024-01-20## 简介本API提供全球主要城市的天气查询服务，支持实时天气和未来7天预报查询。## 基础信息- 服务地址：https://api.weather.example.com- 协议：HTTPS- 数据格式：JSON- 编码：UTF-8。
怎么做一个API接口？
2401_87195067的博客
09-07 2104
其次api名称，请求参数，返回结果必须有确定含义，容易上手，返回结果一般我设计时分为2部分，系统层面信息，业务层面信息，系统层面例如api调用异常，一般用约定好的错误码标识，业务层面就很宽泛，例如银行业务联网核查，查不到用户信息，从系统层面这是OK的，业务层面肯定是不行的，不可能用户在银行有账户却没有用户信息，当然可能数据库在做迁移导致暂时访问为空，这种业务错误也可以通过状态码或者状态标识boolean值+错误信息返回给客户端，这样api出问题可以快速定位是系统问题还是业务问题。】网站上，生成一个项目。
编写后端接口步骤
路小飞
04-21 7542
后端接口书写步骤
Java【后台学习】编写后台接口
WangQingLei0307的博客
10-12 2235
http://blog.csdn.net/qq_29266921/article/details/53692042
如何编写后端接口
hyz4006的博客
12-05 2万+
如何编写后端接口 一、接口的设计与规划 好的程序，一定有一套合理的后端接口。在设计后端接口的时候，要考虑清楚各个方面的需求，最好能有一个操作流程作为指导。 二、使用eclipse创建一个能够连接数据库的spring boot项目 filenewspring starter project填写名称选则依赖MySQL DriverSpring Data JPASpring Web完成 打开eclips...
后端开发——接口篇
追求幸福，探索未知的博客
08-17 1万+
restful rpc 后端开发 接口
如何写一个后端接口
weixin_61728046的博客
10-20 866
如何写一个后端接口
微商城后端接口项目包含API接口说明文档等
06-15
微商城后端接口项目是一个基于Vue前端框架和PHP后端技术构建的电子商务平台。这个项目的核心在于实现微商城的业务逻辑，提供API接口供前端调用，以完成用户交互、商品展示、订单处理、支付系统等功能。下面我们将...
前后端分离之springboot+idea写后端接口
03-25
现在项目开发都是前后端分离,该代码主要是教初学者使用springboot开发接口,其中包括数据返回的包装类,自定义异常,返回码的枚举等,并进行简单的测试,达到抛砖引玉的作用,初学者能更容易地接受,共同进步.
后端接口测试报告1
08-04
在本文中，我们将深入探讨一个后端接口测试报告，该报告涉及到并发测试、接口性能评估以及具体的接口测试用例。 首先，我们关注并发测试。并发测试是衡量系统在多个用户同时访问时的性能和稳定性的关键指标。在这个...
【后端写API接口文档说明书】
最新发布
weixin_72986432的博客
02-20 988
API 接口文档是前后端联调、第三方调用的关键，它应该清晰、准确、规范，确保前端或其他调用方能够正确理解和使用你的接口。
前后端能不能这样约定接口
hezheqiang的专栏
08-28 1562
现在开发的项目，尤其是管理后台的项目，CURD操作是非常频繁的，如果接口约定的不好，后端就需要开发各种Api，前端人员也需要在Api文件中添加多个Api，开发成本不知不觉就增加了。 所以，针对比较普遍的CURD操作，前后端在接口上就需要制定一些约定。 一、添加和修改 1.添加操作和修改操作约定成一个接口。 添加一般情况下是没有ID的，修改一般情况下是有ID的。两个操作的其他字段其实都是一样的...
【编程规范】 后端API接口设计编写与文档编写参考
Jerry‘s word
09-07 2万+
一般前后端分离项目会拥有不同的数据格式，例如 json、url等。这里要通过文档的形式同前后端一起确定好数据阐述的格式。接口地址：不包含接口BASE地址。请求方式: get、post、put、delete等。请求参数：数据格式（默认json）、数据类型、是否必填、中文描述。响应参数：类型、中文描述。这里的接口文档一般就是对应后台的实体，即RequestVo（调用后台接口访问的实体）和给往前端的ResponseVo（前台调用接口时前往的实体）。
[thinking]-如何写好一个接口或者方法
wlwork66的博客
03-11 236
【1】先做null的判定，如果是null，应该返回还是。。。 如果是String或者其他引用类型，都需要进行null判断 如果是String 记得 StringUtils.trim() 【2】波哥的核心想法是：你的接口一定要弄不死 弄不死的接口是什么？接口百分之百会返回消息给前端！！！ 就是出现了异常，我们需要catch，不同的情况，进行不同的返回 【3】切割处理 将一个大的方法，尽量小的切割为一...
如何优雅地写后端API接口
热门推荐
王德昌的博客
12-23 2万+
在移动互联网，分布式、微服务盛行的今天，现在项目绝大部分都采用的微服务框架，前后端分离方式。前后端的工作职责越来越明确，现在的前端都称之为大前端，技术栈以及生态圈都已经非常成熟；以前后端人员瞧不起前端人员，那现在后端人员要重新认识一下前端，前端已经很成体系了 1.接口交互 前端和后端进行交互，前端按照约定请求URL路径，并传入相关参数，后端服务器接收请求，进行业务处理，返回数据给前端。 针对URL路径的restful风格，以及传入参数的公共请求头的要求（如：app_version,api_versio
Visual Studio写后端接口
07-11
对于使用 Visual Studio 编写后端接口，你可以选择使用以下几种方式： 1. ASP.NET Web API：ASP.NET 是微软的一种开发框架，其中的 Web API 可以帮助你构建和发布 RESTful 风格的后端接口。你可以使用 Visual Studio 创建一个新的 ASP.NET Web API 项目，并在其中定义和实现你的接口。 2. ASP.NET Core：ASP.NET Core 是一种跨平台的开发框架，可以用于构建高性能的 Web 应用程序和服务。它提供了强大的功能和灵活的架构，适用于构建后端接口。你可以在 Visual Studio 中创建一个 ASP.NET Core 项目，并使用 C# 或其他支持的语言来编写接口。 3. WCF（Windows Communication Foundation）：WCF 是一种用于构建分布式应用程序的框架，可以支持多种通信协议和传输方式。你可以使用 Visual Studio 创建一个 WCF 项目，并定义和实现你的接口。 以上是一些常见的在 Visual Studio 中编写后端接口的方式，每种方式都有其特点和适用场景。你可以根据自己的需求和技术偏好选择适合的方式进行开发。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值