CloudOptions 配置指南

CloudOptions 继承自 ServerOptions，所以端口、线程数、调试模式、HTTPS 这类基础能力仍然在 ServerOptions 里配置。
这页只讲 Feat Cloud 启动阶段最关键的三项额外能力。

什么时候需要看这页

• 控制器明明写了，但没有被扫描到
• 你要在容器启动前手动注册某个 Bean
• 你想让 Feat Cloud 顺手托管静态资源

你最常用的 3 个配置项

配置项	方法	默认值	典型用途
包扫描	setPackages(String...)	null	控制 Controller / Bean 的扫描范围
外部 Bean	registerBean(String, Object)	空	把启动前已有对象注册进容器
静态资源	setStaticLocations(String)	classpath:static	托管类路径或本地目录里的静态文件

场景 1：控制扫描范围

如果你的启动类和控制器不在同一个合理的根包下，或者你只想限制扫描范围，可以显式设置包路径。

Bootstrap.java

import tech.smartboot.feat.cloud.FeatCloud;

public class Bootstrap {
    public static void main(String[] args) {
        FeatCloud.cloudServer(options -> {
            options.setPackages(
                    "com.example.controller",
                    "com.example.service"
            );
        }).listen();
    }
}

什么时候应该用它：

• 多模块项目里，控制器不在启动类同包或子包
• 你只想扫描少量包，提高启动阶段的可控性
• 你要避免把不相关 demo 或测试类扫进来

Tip

如果你的启动类本身已经位于合理的根包下，很多情况下并不需要写 setPackages(...)。只有在扫描行为不符合预期时，再显式收窄范围。

场景 2：注册外部 Bean

有些对象不是通过 Feat Cloud 自己创建的，比如数据源、第三方客户端、配置对象。这时可以在启动时手动注册。

ExternalBeanDemo.java

import tech.smartboot.feat.cloud.FeatCloud;

public class ExternalBeanDemo {
    public static void main(String[] args) {
        FeatCloud.cloudServer(options -> {
            options.registerBean("dataSource", createDataSource());
            options.registerBean("buildVersion", "1.0.0");
        }).listen();
    }

    private static Object createDataSource() {
        return new Object();
    }
}

这类用法通常出现在：

• 你已经有一套外部初始化逻辑
• 某个对象必须在容器启动前构造好
• 你希望让 @Autowired 能直接拿到该对象

一个容易踩的坑

registerBean(...) 的 key 不能重复。源码里如果发现同名 key，直接抛 FeatException。

options.registerBean("dataSource", ds1);
options.registerBean("dataSource", ds2); // 会失败

所以命名上建议用稳定且业务明确的名字。

场景 3：托管静态资源

Feat Cloud 默认静态资源目录是 classpath:static。如果你项目里有前端页面、上传后的公开文件或静态文档，可以直接改位置。

StaticLocationDemo.java

import tech.smartboot.feat.cloud.FeatCloud;

public class StaticLocationDemo {
    public static void main(String[] args) {
        FeatCloud.cloudServer(options -> {
            options.setStaticLocations("classpath:public");
        }).listen();
    }
}

你可以使用两种路径形式：

// 类路径资源
options.setStaticLocations("classpath:static");
options.setStaticLocations("classpath:public");

// 文件系统目录
options.setStaticLocations("/var/www/static");
options.setStaticLocations("./public");

默认行为

当你配置静态资源目录后，Feat Cloud 会使用静态资源处理器来提供这些能力：

• 访问目录时自动返回 index.html
• 自动识别常见文件类型
• 基于 Last-Modified 支持缓存
• 找不到资源时返回 404

Caution

setStaticLocations(...) 不只是记住一个路径，它会顺手创建一个新的 Router 来挂载静态资源处理器。所以如果你还要自定义底层路由，请明确知道谁是最终生效的 Router。

组合使用示例

实际项目里，这三个配置项经常一起出现：

CloudOptionsDemo.java

import tech.smartboot.feat.cloud.FeatCloud;

public class CloudOptionsDemo {
    public static void main(String[] args) {
        FeatCloud.cloudServer(options -> {
            options.port(8080);
            options.debug(true);

            options.setPackages("com.example.controller", "com.example.service");
            options.registerBean("dataSource", createDataSource());
            options.setStaticLocations("classpath:public");
        }).listen();
    }

    private static Object createDataSource() {
        return new Object();
    }
}

这段代码表达的启动策略是：

• 用 ServerOptions 部分配置基础服务行为
• 用 CloudOptions 部分控制扫描、注入和静态资源

进阶：替换默认 Router

如果你需要完全自定义路由入口，而不是只靠 setStaticLocations(...) 生成的静态资源 Router，可以直接替换：

options.setRouter(customRouter);

这个能力属于高级扩展场景，通常只有在你明确需要接管更底层的路由行为时才会用到。

常见问题

控制器不生效，但程序能启动

优先检查：

1. 控制器所在包是否在 setPackages(...) 范围内
2. 启动类是否位于合理的根包下
3. 是否因为扫描范围过窄，把实际控制器排除掉了

Bean 注入失败

优先检查：

1. 注册时使用的 key 是否与注入预期一致
2. 是否重复注册了同名 Bean
3. Bean 是否在容器真正启动前完成注册

静态资源一直 404

优先检查：

1. 路径是否真的存在
2. 类路径资源是否放在 resources 下并已打包进去
3. classpath: 前缀是否写对

下一步

• Controller 开发实践：把控制器、参数绑定和路径映射写完整
• ServerOptions 配置指南：回到基础服务层继续调端口、线程、HTTPS
• MyBatis 集成：进入真实数据访问场景