如何写一个接口

1
用户（浏览器/APP）
2
      ↓
3
  Controller层（接口层）  ← 你写的接口就在这里！
4
      ↓
5
  Service层（业务逻辑层）
6
      ↓
7
  Mapper/DAO层（数据访问层）
8
      ↓
9
  数据库

1
第一步：看项目中已有的接口是怎么写的（最重要！）
2
第二步：在Controller里写方法，定义接口地址和参数
3
第三步：在Service里写业务逻辑
4
第四步：在Mapper里写SQL
5
第五步：用Postman测试

1
@Mapper
2
public interface UserMapper {
3

4
    // 分页查询用户列表
5
    List<UserVo> selectList(
6
        @Param("userName") String userName,
7
        @Param("phone") String phone
8
    );
9
}

1
@PostMapping("/list")
2
public Result list(@RequestBody UserQueryVo query) {
3
    PageHelper.startPage(query.getPageNum(), query.getPageSize());
4
    List<UserVo> list = userService.list(query);
5
    PageInfo<UserVo> pageInfo = new PageInfo<>(list);
6
    return Result.success(pageInfo);
7
}

1
@Data
2
public class UserQueryVo {
3
    private String userName;     // 用户名
4
    private String phone;        // 手机号
5
    private Integer pageNum = 1;  // 页码，默认1
6
    private Integer pageSize = 10; // 每页条数，默认10
7
}

1
/**
2
 * 修改用户
3
 * 请求方式：PUT
4
 * 接口地址：/api/user/update
5
 */
6
@PutMapping("/update")
7
public Result update(@RequestBody UserDto userDto) {
8
    userService.update(userDto);
9
    return Result.success("修改成功");
10
}

1
@Override
2
public void update(UserDto userDto) {
3
    // 1. 检查用户是否存在
4
    User user = userMapper.selectById(userDto.getId());
5
    if (user == null) {
6
        throw new BusinessException("用户不存在");
7
    }
8

9
    // 2. 更新数据
10
    userDto.setUpdateTime(new Date());
11
    userMapper.updateById(userDto);
12
}

1
// 在UserMapper中添加
2
User selectById(@Param("id") Integer id);
3
int updateById(UserDto userDto);

1
/**
2
 * 删除用户
3
 * 请求方式：DELETE
4
 * 接口地址：/api/user/delete/{id}
5
 */
6
@DeleteMapping("/delete/{id}")
7
public Result delete(@PathVariable("id") Integer id) {
8
    userService.deleteById(id);
9
    return Result.success("删除成功");
10
}

1
@Override
2
public void deleteById(Integer id) {
3
    // 建议用逻辑删除，而不是物理删除
4
    userMapper.logicDeleteById(id);
5
}
6

7
@Override
8
public void deleteByIds(List<Integer> idList) {
9
    userMapper.logicDeleteByIds(idList);
10
}

1
// 在UserMapper中添加
2
int logicDeleteById(@Param("id") Integer id);
3
int logicDeleteByIds(@Param("idList") List<Integer> idList);

1
<update id="logicDeleteById">
2
    UPDATE sys_user
3
    SET deleted = 1
4
    WHERE id = #{id}
5
</update>
6

7
<update id="logicDeleteByIds">
8
    UPDATE sys_user
9
    SET deleted = 1
10
    WHERE id IN
11
    <foreach collection="idList" item="id" open="(" separator="," close=")">
12
        #{id}
13
    </foreach>
14
</update>

1
数据库字段（下划线命名）            Java实体类字段（驼峰命名）
2
─────────────────────            ─────────────────────
3
order_info表：                    OrderDetailVo：
4
  order_no        ──映射──→         orderNo
5
  total_price     ──映射──→         totalPrice
6
  create_time     ──映射──→         createTime
7

8
order_item表：                    OrderItemVo：
9
  order_id        ──映射──→         orderId
10
  product_name    ──映射──→         productName

1
{
2
    "code": 200,
3
    "message": "操作成功",
4
    "data": {
5
        "id": 1,
6
        "orderNo": "OD001",
7
        "totalPrice": 5999.00,
8
        "createTime": "2026-05-07 10:30:00",
9
        "itemList": [
10
            {"id": 1, "orderId": 1, "productName": "手机", "quantity": 1, "price": 4999.00},
11
            {"id": 2, "orderId": 1, "productName": "耳机", "quantity": 2, "price": 500.00}
12
        ]
13
    }
14
}

1
/**
2
 * 查询订单详情
3
 * 请求方式：GET
4
 * 接口地址：/api/order/detail/{id}
5
 */
6
@GetMapping("/detail/{id}")
7
public Result detail(@PathVariable("id") Integer id) {
8
    OrderDetailVo order = orderService.getDetailById(id);
9
    return Result.success(order);
10
}

1
@Mapper
2
public interface OrderMapper {
3
    // 一条SQL查询订单详情（主表+子表），MyBatis自动通过resultMap组装
4
    OrderDetailVo selectDetailById(@Param("id") Integer id);
5
}

1
Mapper接口（Java）          Mapper XML（SQL）
2
┌──────────────────┐      ┌──────────────────────┐
3
│ selectById(id)   │ ──→  │ <select id="selectById"> │
4
│ insert(user)     │ ──→  │ <insert id="insert">     │
5
│ updateById(user) │ ──→  │ <update id="updateById">  │
6
│ deleteById(id)   │ ──→  │ <delete id="deleteById">  │
7
└──────────────────┘      └──────────────────────┘

1
<!-- UserMapper.xml 头部 -->
2
<?xml version="1.0" encoding="UTF-8"?>
3
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
4
    "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
5
<mapper namespace="com.example.mapper.UserMapper">
6

7
    <!-- 你的SQL写在这里 -->
8

9
</mapper>

1
<!-- #{} 推荐！预编译处理，防SQL注入 -->
2
WHERE user_name = #{userName}
3
-- 实际执行：WHERE user_name = ?
4

5
<!-- ${} 字符串拼接，有SQL注入风险，尽量少用 -->
6
WHERE user_name = '${userName}'
7
-- 实际执行：WHERE user_name = '张三'
8

9
<!-- ${} 的使用场景：动态表名、动态列名（不能用#{}的情况） -->
10
ORDER BY ${orderColumn} ${orderDir}

1
// 请求：GET /api/user/list?name=张三&pageNum=1
2
@GetMapping("/list")
3
public Result list(
4
    @RequestParam("name") String name,
5
    @RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum
6
) {
7
    // ...
8
}

1
// 请求：GET /api/user/detail/123
2
@GetMapping("/detail/{id}")
3
public Result detail(@PathVariable("id") Integer id) {
4
    // id = 123
5
}

1
// 请求：POST /api/user/add
2
// Body: {"userName":"张三","phone":"13800138000"}
3
@PostMapping("/add")
4
public Result add(@RequestBody UserDto userDto) {
5
    // userDto.getUserName() = "张三"
6
}

1
{
2
    "code": 200,
3
    "message": "操作成功",
4
    "data": {
5
        "userId": 1,
6
        "userName": "张三"
7
    }
8
}

1
{
2
    "code": 500,
3
    "message": "用户名已存在",
4
    "data": null
5
}

1
// 错误：Integer类型不能用 != "" 判断
2
if (userId != null && userId != "") {  // 编译报错！
3

4
// 正确：Integer只判断是否为null
5
if (userId != null) {
6

7
// 字符串才需要判断空
8
if (StringUtils.isNotEmpty(userName)) {

1
// 错误：循环调用单条插入，效率很低
2
for (User user : userList) {
3
    userMapper.insert(user);
4
}
5

6
// 正确：使用批量插入
7
userMapper.insertBatch(userList);