Java增删改查类接口设计深入讲解

get    /api/v1/users          - 查询用户列表（支持分页、排序、过滤）
get    /api/v1/users/{id}     - 查询单个用户
post   /api/v1/users          - 创建新用户
put    /api/v1/users/{id}     - 完整更新用户（替换）
patch  /api/v1/users/{id}     - 部分更新用户（修改部分字段）
delete /api/v1/users/{id}     - 删除用户

get /api/v1/users/{userid}/orders  - 查询用户的所有订单
post /api/v1/users/{userid}/orders - 为用户创建订单

post /api/v1/users/search
{
    "filters": [
        {"field": "name", "operator": "like", "value": "张"},
        {"field": "age", "operator": "gte", "value": 18},
        {"field": "age", "operator": "lte", "value": 60},
        {"field": "status", "operator": "in", "value": [1, 2, 3]}
    ],
    "sorts": [
        {"field": "createtime", "direction": "desc"}
    ],
    "pagination": {
        "page": 1,
        "size": 20
    },
    "fields": ["id", "name", "age", "status"]  // 指定返回字段
}

get /api/v1/users?$filter=contains(name,'张') and age ge 18 and status in (1,2,3)&$orderby=createtime desc&$top=20&$skip=0&$select=id,name,age,status

query {
  users(filter: {namecontains: "张", agegte: 18}) {
    id
    name
    age
    status
    orders(limit: 5) {
      id
      amount
    }
  }
}

get /api/v1/users/batch?ids=1,2,3,4,5

post /api/v1/users/batch
[
    { "name": "用户1", "age": 20 },
    { "name": "用户2", "age": 25 }
]

patch /api/v1/users/batch
{
    "ids": [1, 2, 3],
    "data": { "status": 1 }  // 批量将这三个用户的状态改为1
}

delete /api/v1/users/batch?ids=1,2,3

@tablelogic
private integer deleted;

@getmapping("/export")
public responseentity<resource> exportusers(exportquery query) {
    // 1. 查询数据（可能包含大量数据）
    list<uservo> users = userservice.queryforexport(query);
    
    // 2. 生成excel或csv
    byte[] bytes = excelexportservice.export(users);
    
    // 3. 构建下载响应
    httpheaders headers = new httpheaders();
    headers.add(httpheaders.content_disposition, 
                "attachment; filename=users_" + system.currenttimemillis() + ".xlsx");
    return responseentity.ok()
            .headers(headers)
            .body(new bytearrayresource(bytes));
}

@postmapping("/import")
public apiresponse<importresult> importusers(@requestparam multipartfile file) {
    // 1. 解析文件
    list<userimportdto> rows = parsefile(file);
    
    // 2. 校验数据
    list<validationerror> errors = validaterows(rows);
    if (!errors.isempty()) {
        return apiresponse.fail("数据校验失败", errors);
    }
    
    // 3. 批量入库
    int successcount = userservice.batchinsert(rows);
    
    return apiresponse.success(new importresult(successcount));
}

post   /api/v1/users/draft          - 保存草稿
put    /api/v1/users/{id}/publish   - 发布草稿
put    /api/v1/users/{id}/recall    - 撤回发布

get /api/v1/users/{id}/versions     - 获取所有历史版本
get /api/v1/users/{id}/versions/{versionid} - 获取特定版本
put /api/v1/users/{id}/versions/{versionid}/restore - 回滚到指定版本

// 配置多租户拦截器
@bean
public mybatisplusinterceptor mybatisplusinterceptor() {
    mybatisplusinterceptor interceptor = new mybatisplusinterceptor();
    interceptor.addinnerinterceptor(new tenantlineinnerinterceptor(
        new tenantlinehandler() {
            @override
            public expression gettenantid() {
                // 从请求上下文获取当前租户id
                return new longvalue(tenantcontextholder.getcurrenttenantid());
            }
            @override
            public string gettenantidcolumn() {
                return "tenant_id";
            }
            @override
            public boolean ignoretable(string tablename) {
                return "sys_config".equals(tablename); // 系统表不加租户过滤
            }
        }
    ));
    return interceptor;
}

controller层：接收http请求，参数校验，响应封装
    ↓
service层：业务逻辑，事务管理，对象转换
    ↓
dao层：数据访问，sql执行
    ↓
database

interface层（接口层）：rest api、消息队列监听、定时任务等
    ↓
application层（应用层）：协调领域对象完成用例，事务管理
    ↓
domain层（领域层）：核心业务逻辑，聚合根、实体、值对象
    ↓
infrastructure层（基础设施层）：数据库访问、外部服务调用

写操作（command）：
post /api/v1/users → command → 写入主数据库（event sourcing可选）

读操作（query）：
get /api/v1/users → query → 从只读副本/缓存读取

// 贫血模型
@entity
public class user {
    private long id;
    private string name;
    private integer status;
    // 只有getter/setter，无业务方法
}

@service
public class userservice {
    public void activeuser(long userid) {
        user user = userrepository.findbyid(userid);
        user.setstatus(1);  // 业务逻辑在service
        userrepository.save(user);
    }
}

// 充血模型
@entity
public class user {
    private long id;
    private string name;
    private integer status;
    
    public void activate() {
        if (this.status == 2) {
            throw new businessexception("已冻结用户无法激活");
        }
        this.status = 1;
        // 触发领域事件
        domaineventpublisher.publish(new useractivatedevent(this.id));
    }
}

@service
public class userservice {
    public void activeuser(long userid) {
        user user = userrepository.findbyid(userid);
        user.activate();  // 业务逻辑在领域对象中
        userrepository.save(user);
    }
}

@mapper(componentmodel = "spring",
        uses = {datemapper.class, enummapper.class},
        imports = {localdatetime.class})
public interface userassembler {
    
    // request → entity（创建场景）
    @mapping(target = "createtime", expression = "java(localdatetime.now())")
    @mapping(target = "updatetime", expression = "java(localdatetime.now())")
    @mapping(target = "deleted", constant = "0")
    userentity createreqtoentity(usercreaterequest request);
    
    // request → entity（更新场景）
    @mapping(target = "createtime", ignore = true)
    @mapping(target = "deleted", ignore = true)
    @mapping(target = "updatetime", expression = "java(localdatetime.now())")
    void updatereqtoentity(userupdaterequest request, @mappingtarget userentity entity);
    
    // entity → vo（查询场景）
    @mapping(source = "createtime", target = "createtimestr", dateformat = "yyyy-mm-dd hh:mm:ss")
    @mapping(source = "status", target = "statusdesc", qualifiedbyname = "statustodesc")
    uservo entitytovo(userentity entity);
    
    // 批量转换
    list<uservo> entitylisttovolist(list<userentity> entities);
}

public class userrequest {
    @notnull(groups = {update.class}, message = "id不能为空")
    private long id;
    
    @notblank(groups = {create.class, update.class}, message = "姓名不能为空")
    private string name;
    
    @notnull(groups = {create.class}, message = "年龄不能为空")
    @min(value = 1, groups = {create.class, update.class})
    private integer age;
}

// 使用
@validated(create.class)
public apiresponse create(@requestbody @valid userrequest request) { }

@target({field})
@retention(runtime)
@constraint(validatedby = phonevalidator.class)
public @interface phone {
    string message() default "手机号格式不正确";
    class<?>[] groups() default {};
    class<? extends payload>[] payload() default {};
}

public class phonevalidator implements constraintvalidator<phone, string> {
    private static final pattern pattern = pattern.compile("^1[3-9]\\d{9}$");
    
    @override
    public boolean isvalid(string value, constraintvalidatorcontext context) {
        if (value == null || value.isempty()) return true;
        return pattern.matcher(value).matches();
    }
}

@data
public class pagerequest {
    @min(1)
    private integer page = 1;
    
    @min(1)
    @max(200)
    private integer size = 20;
    
    private string sort;
    private string order = "desc";
    
    // 获取排序对象（带白名单校验）
    public list<orderitem> getorderitems(class<?> entityclass) {
        if (stringutils.isblank(sort)) {
            return collections.emptylist();
        }
        // 白名单校验：只能使用entity中存在的字段
        try {
            entityclass.getdeclaredfield(sort);
        } catch (nosuchfieldexception e) {
            throw new businessexception("排序字段不存在");
        }
        return collections.singletonlist(
            "asc".equalsignorecase(order) ? 
            orderitem.asc(sort) : orderitem.desc(sort)
        );
    }
}

public pageresult<uservo> listusers(pagerequest pagerequest, userquery query) {
    // 构建分页对象
    page<userentity> page = new page<>(pagerequest.getpage(), pagerequest.getsize());
    
    // 构建查询条件
    lambdaquerywrapper<userentity> wrapper = wrappers.lambdaquery(userentity.class)
        .like(stringutils.isnotblank(query.getname()), userentity::getname, query.getname())
        .eq(query.getstatus() != null, userentity::getstatus, query.getstatus())
        .between(query.getstarttime() != null && query.getendtime() != null,
                userentity::getcreatetime, query.getstarttime(), query.getendtime());
    
    // 添加排序
    list<orderitem> orderitems = pagerequest.getorderitems(userentity.class);
    if (!orderitems.isempty()) {
        page.setorders(orderitems);
    } else {
        page.addorder(orderitem.desc("create_time"));
    }
    
    // 执行查询
    ipage<userentity> entitypage = usermapper.selectpage(page, wrapper);
    
    // 转换结果
    return pageresult.of(entitypage, userassembler.entitylisttovolist(entitypage.getrecords()));
}

@cacheable(value = "user", key = "#id", unless = "#result == null")
public uservo getuserbyid(long id) {
    userentity entity = usermapper.selectbyid(id);
    return userassembler.entitytovo(entity);
}

@cacheevict(value = "user", key = "#id")
public void updateuser(long id, userupdaterequest request) {
    // 更新操作清除缓存
}

@cacheevict(value = "user", allentries = true)
public void deleteuser(long id) {
    // 删除操作清除所有用户缓存
}

public pageresult<uservo> listusers(pagerequest pagerequest) {
    // 使用缓存key包含分页参数
    string cachekey = "users:page:" + pagerequest.getpage() + 
                     ":size:" + pagerequest.getsize() + 
                     ":sort:" + pagerequest.getsort();
    
    return redistemplate.execute(session -> {
        // 尝试从缓存获取
        pageresult<uservo> cached = (pageresult<uservo>) redistemplate.opsforvalue().get(cachekey);
        if (cached != null) return cached;
        
        // 缓存未命中，查询数据库
        pageresult<uservo> result = queryfromdatabase(pagerequest);
        redistemplate.opsforvalue().set(cachekey, result, 5, timeunit.minutes);
        return result;
    });
}

@transactional(rollbackfor = exception.class)
public void createuserwithroles(usercreaterequest request, list<long> roleids) {
    // 1. 创建用户
    userentity user = userassembler.createreqtoentity(request);
    usermapper.insert(user);
    
    // 2. 分配角色
    if (collectionutils.isnotempty(roleids)) {
        roleids.foreach(roleid -> {
            userroleentity relation = new userroleentity();
            relation.setuserid(user.getid());
            relation.setroleid(roleid);
            userrolemapper.insert(relation);
        });
    }
}

@preauthorize("hasrole('admin')")
@deletemapping("/{id}")
public apiresponse deleteuser(@pathvariable long id) {
    // 只有管理员可以删除用户
    userservice.deleteuser(id);
    return apiresponse.success();
}

public pageresult<uservo> listusers(userquery query) {
    // 获取当前用户的数据范围
    set<long> accessibledeptids = getcurrentuserdeptids();
    
    lambdaquerywrapper<userentity> wrapper = wrappers.lambdaquery(userentity.class)
        .in(userentity::getdeptid, accessibledeptids)  // 只查询有权限的部门
        .like(...);
    
    // 执行查询
    return queryusers(query, wrapper);
}

@jsonserialize(using = phonedesensitizeserializer.class)
private string phone;

public class phonedesensitizeserializer extends jsonserializer<string> {
    @override
    public void serialize(string value, jsongenerator gen, serializerprovider provider) 
            throws ioexception {
        if (value == null || value.length() < 7) {
            gen.writestring(value);
            return;
        }
        // 手机号脱敏：138****1234
        gen.writestring(value.substring(0, 3) + "****" + value.substring(7));
    }
}

@restcontroller
public class usercontroller {
    // 每秒允许100个请求
    private final ratelimiter ratelimiter = ratelimiter.create(100.0);
    
    @getmapping
    public apiresponse listusers() {
        if (!ratelimiter.tryacquire(1)) {
            throw new ratelimitexception("请求过于频繁，请稍后再试");
        }
        // 正常处理
    }
}

@sentinelresource(
    value = "listusers",
    blockhandler = "handleblock",
    blockhandlerclass = userblockhandler.class
)
public pageresult<uservo> listusers(pagerequest pagerequest) {
    return userservice.listusers(pagerequest);
}

// mybatis-plus安全写法
wrapper.eq("name", name);  // 参数化

// mybatis xml安全写法
<select id="findbyname">
    select * from user where name = #{name}  <!-- 参数化 -->
</select>

// 安全写法：使用占位符
string sql = "select * from user where name = ?";
preparedstatement ps = connection.preparestatement(sql);
ps.setstring(1, name);

// 字符串拼接 - 高危！！！
string sql = "select * from user where name = '" + name + "'";

// mybatis ${} - 高危！！！
<select id="findbyname">
    select * from user where name = '${name}'
</select>

private static final set<string> allowed_sort_fields = 
    set.of("id", "name", "age", "createtime");

public void validatesortfield(string field) {
    if (!allowed_sort_fields.contains(field)) {
        throw new businessexception("非法排序字段");
    }
}

// 1次查询获取用户列表
list<userentity> users = usermapper.selectlist(wrapper);
// n次查询获取角色名称
for (userentity user : users) {
    string rolename = rolemapper.selectnamebyid(user.getroleid());
    // 设置到vo中
}

select u.*, r.name as role_name 
from user u 
left join role r on u.role_id = r.id

list<userentity> users = usermapper.selectlist(wrapper);
// 提取所有roleid
set<long> roleids = users.stream().map(userentity::getroleid).collect(collectors.toset());
// 批量查询角色（1次查询）
list<roleentity> roles = rolemapper.selectbatchids(roleids);
map<long, string> rolemap = roles.stream().collect(collectors.tomap(roleentity::getid, roleentity::getname));
// 填充到vo

<resultmap id="userwithroles" type="userentity">
    <id column="id" property="id"/>
    <result column="name" property="name"/>
    <collection property="roles" oftype="roleentity" 
                select="selectrolesbyuserid" column="id"/>
</resultmap>

public pageresult<uservo> listusers(pagerequest pagerequest, userquery query) {
    // 游标分页：基于上一页最后一条记录的id
    long lastid = query.getlastid();  // 前端传回上一页的最后id
    
    lambdaquerywrapper<userentity> wrapper = wrappers.lambdaquery(userentity.class)
        .gt(lastid != null, userentity::getid, lastid)  // 从上次位置开始
        .orderbyasc(userentity::getid)
        .last("limit " + pagerequest.getsize());
    
    // 这种方式的性能是o(1)，与翻页深度无关
}

select * from user 
where id in (
    select id from user 
    where condition = 'xxx' 
    order by id 
    limit 100000, 20
)

// 使用redis缓存总数
string countkey = "users:count:" + query.hashcode();
long total = redistemplate.opsforvalue().get(countkey);
if (total == null) {
    total = usermapper.selectcount(wrapper);
    redistemplate.opsforvalue().set(countkey, total, 5, timeunit.minutes);
}

// 批量插入使用 values (?, ?), (?, ?)
public boolean batchinsert(list<userentity> users) {
    string sql = "insert into user (name, age) values (?, ?)";
    sqlsession sqlsession = sqlsessionfactory.opensession(executortype.batch);
    try {
        for (userentity user : users) {
            sqlsession.insert("insertuser", user);
        }
        sqlsession.commit();
        return true;
    } finally {
        sqlsession.close();
    }
}

// mybatis-plus批量插入
userservice.savebatch(users, 1000);  // 每1000条一批

-- 使用case when批量更新
update user set 
    status = case id 
        when 1 then 0 
        when 2 then 1 
        when 3 then 0 
    end,
    update_time = now()
where id in (1, 2, 3)

spring:
  datasource:
    hikari:
      # 最小空闲连接数
      minimum-idle: 10
      # 最大连接数
      maximum-pool-size: 50
      # 连接超时时间
      connection-timeout: 30000
      # 空闲连接超时
      idle-timeout: 600000
      # 连接最大生命周期
      max-lifetime: 1800000
      # 连接测试查询
      connection-test-query: select 1

/api/v1/users
/api/v2/users

@restcontroller
@requestmapping("/api/v1/users")
public class userv1controller { }

@restcontroller
@requestmapping("/api/v2/users")
public class userv2controller { }

@getmapping
@apiversion("v1")  // 自定义注解
public apiresponse listusersv1() { }

@getmapping
@apiversion("v2")
public apiresponse listusersv2() { }

public class uservo {
    // 旧字段保留
    private integer status;
    
    // 新增字段，替代旧字段
    private string statusdesc;
    
    // 字段变化：重构后保留兼容
    private string phone;
    
    @jsonproperty("phonenumber")  // 提供别名，兼容旧客户端
    public string getphonenumber() {
        return this.phone;
    }
}

@extendwith(mockitoextension.class)
class userservicetest {
    
    @mock
    private usermapper usermapper;
    
    @mock
    private userassembler userassembler;
    
    @injectmocks
    private userserviceimpl userservice;
    
    @test
    void shouldcreateusersuccessfully() {
        // given
        usercreaterequest request = new usercreaterequest();
        request.setname("张三");
        request.setage(25);
        
        userentity entity = new userentity();
        entity.setname("张三");
        
        when(userassembler.createreqtoentity(request)).thenreturn(entity);
        when(usermapper.insert(entity)).thenreturn(1);
        
        // when
        userservice.createuser(request);
        
        // then
        verify(usermapper).insert(entity);
    }
}

@springboottest
@testcontainers
class usercontrollerintegrationtest {
    
    @container
    static postgresqlcontainer<?> postgres = new postgresqlcontainer<>("postgres:15")
        .withdatabasename("testdb")
        .withusername("test")
        .withpassword("test");
    
    @autowired
    private testresttemplate resttemplate;
    
    @test
    void shouldqueryuserssuccessfully() {
        // when
        responseentity<apiresponse> response = resttemplate.getforentity(
            "/api/v1/users?page=1&size=10",
            apiresponse.class
        );
        
        // then
        assertthat(response.getstatuscode()).isequalto(httpstatus.ok);
        assertthat(response.getbody().getcode()).isequalto(200);
    }
}

前端 → api gateway → 服务a / 服务b / 服务c

前端 → 聚合服务 → 服务a
                → 服务b
                → 服务c

service a (命令) → 发布事件 → kafka → 消费事件 → service b