文档控制器框架

从 Spring Boot 到 Nexy

Nexy 的模块化路由器保持了 Spring Boot 应用程序的形状：@RestController 是一个 @Controller 类，@Service 是通过 __init__ 注入的 @Injectable，模块将它们分组。 Bean Validation变成 Pydantic，并且内置了springdoc的 OpenAPI 页面。

下面的每个部分都展示了 Spring Boot 习惯，然后是 Nexy 中的相同内容。

打开模块化路由器

演示应用程序.java

@SpringBootApplicationpublic class DemoApplication {    public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); }}

根模块是 nexyconfig.py 的一个字段，nx dev 为它服务：

nexyconfig.py

from nexy.core.models import NexyConfigModel from src.apps.app_module import AppModule  class NexyConfig(NexyConfigModel):    useRouter = AppModule

Spring通过扫描包来找到它的bean； Nexy 模块列出了它们，因此模块所服务的内容被写在一个地方。

控制器一个

HelloController.java

@RestController@RequestMapping("/api/hello")public class HelloController {    @GetMapping    public Map<String, String> hello() {        return Map.of("message", "Hello");    }}

路径是 @Controller 的第一个参数，方法名称是 HTTP 动词：

src/apps/hello/hello_controller.py

from nexy.decorators import Controller  @Controller("/api/hello")class HelloController:    async def get(self) -> dict:        return {"message": "Hello"}

控制器的每个动词都有一个处理程序，因此一条路径上的 @GetMapping 和 @PostMapping 是一个类的 get 和 post 方法。 GET /items 和 GET /items/{id} 是两个控制器。

`@PathVariable` 和 `@RequestParam`

用户控制器.java

@GetMapping("/api/users/{id}")public Map<String, Object> user(@PathVariable long id,                                @RequestParam(defaultValue = "") String fields) {    return Map.of("id", id, "fields", fields);}

{id} 保留在路径中并成为类型化参数；请求参数是一个带有默认值的参数：

src/apps/users/user_controller.py

from nexy.decorators import Controller  @Controller("/api/users/{id}")class UserController:    async def get(self, id: int, fields: str = "") -> dict:        return {"id": id, "fields": fields}

非数字 id 回答 404，以及错误类型 422 的请求参数。

`@RequestBody`、`@Valid` 和 `ResponseEntity`

NewItem.java

public record NewItem(@NotBlank @Size(max = 100) String name,                      @Positive double price) {}

ItemController.java

@PostMapping("/api/items")public ResponseEntity<NewItem> create(@Valid @RequestBody NewItem item) {    return ResponseEntity.status(HttpStatus.CREATED).body(item);}

记录及其注释是一个 Pydantic 模型，始终经过验证，并且 @UseResponse 设置状态：

src/apps/items/items_controller.py

from pydantic import BaseModel, Field from nexy.decorators import Controller, UseResponse  class NewItem(BaseModel):    name: str = Field(min_length=1, max_length=100)    price: float = Field(gt=0)  @Controller("/api/items")class ItemsController:    @UseResponse(status_code=201)    async def post(self, item: NewItem) -> NewItem:        return item

`@Service` 和构造函数注入

GreetingService.java

@Servicepublic class GreetingService {    public String greet(String name) { return "Hello " + name; }} @RestController@RequestMapping("/api/greet")public class GreetingController {    private final GreetingService greetings;     public GreetingController(GreetingService greetings) { this.greetings = greetings; }     @GetMapping    public Map<String, String> greet(@RequestParam String name) {        return Map.of("message", greetings.greet(name));    }}

@Service 是 @Injectable()，__init__ 的注释告诉容器要注入什么：

src/apps/greet/greeting_service.py

from nexy.decorators import Injectable  @Injectable()class GreetingService:    def greet(self, name: str) -> str:        return f"Hello {name}"

src/apps/greet/greeting_controller.py

from nexy.decorators import Controller from .greeting_service import GreetingService  @Controller("/api/greet")class GreetingController:    def __init__(self, greetings: GreetingService) -> None:        self.greetings = greetings     async def get(self, name: str) -> dict:        return {"message": self.greetings.greet(name)}

默认情况下，bean 是单例，就像在 Spring 中一样。 @RequestScope 是 @Injectable(scope=Scope.REQUEST)，@Scope("prototype") 是 Scope.TRANSIENT。请参阅依赖项注入。

`@Configuration` 类和模块

模块列出其控制器及其使用的服务，并导出其他模块可能注入的内容：

src/apps/greet/greet_module.py

from nexy.decorators import Module from .greeting_controller import GreetingControllerfrom .greeting_service import GreetingService  @Module()class GreetModule:    controllers = [GreetingController]    providers = [GreetingService]    exports = [GreetingService]

根模块导入其他模块：

src/apps/app_module.py

from nexy.decorators import Module from .admin.admin_module import AdminModulefrom .greet.greet_module import GreetModulefrom .health_controller import PublicHealthControllerfrom .hello.hello_controller import HelloControllerfrom .items.items_controller import ItemsControllerfrom .orders.orders_controller import OrderControllerfrom .posts.posts_module import PostsModulefrom .signup.signup_controller import SignupControllerfrom .users.user_controller import UserControllerfrom .users.users_page_controller import UsersPageControllerfrom .ws.echo_controller import EchoController  @Module()class AppModule:    controllers = [        HelloController,        UserController,        ItemsController,        OrderController,        SignupController,        PublicHealthController,        UsersPageController,        EchoController,    ]    imports = [GreetModule, AdminModule, PostsModule]

`@RequestMapping` 在课堂上

管理控制器.java

@RestController@RequestMapping("/admin")public class AdminController {    @GetMapping("/stats")    public Map<String, Integer> stats() { return Map.of("users", 3); }     @GetMapping("/health")    public Map<String, String> health() { return Map.of("status", "UP"); }}

共享映射是模块的 prefix，每个子路径是该模块的控制器：

src/apps/admin/admin_controllers.py

from nexy.decorators import Controller, UseGuard from .guards import require_admin  @Controller("/stats")@UseGuard(require_admin)class StatsController:    async def get(self) -> dict:        return {"users": 3}  @Controller("/health")@UseGuard(require_admin)class HealthController:    async def get(self) -> dict:        return {"status": "UP"}

src/apps/admin/admin_module.py

from nexy.decorators import Module from .admin_controllers import HealthController, StatsController  @Module(prefix="/admin")class AdminModule:    controllers = [StatsController, HealthController]

春季安全

安全配置.java

@BeanSecurityFilterChain filters(HttpSecurity http) throws Exception {    return http.authorizeHttpRequests(auth -> auth            .requestMatchers("/admin/**").hasRole("ADMIN")            .anyRequest().permitAll())        .build();}

守卫是一种在请求无法继续时引发的函数。 @UseGuard 将其放在控制器上，或放在一种方法上，例如 @PreAuthorize：

src/apps/admin/guards.py

from nexy.http import Header, HTTPException  def require_admin(x_role: str = Header("")) -> None:    if x_role != "admin":        raise HTTPException(status_code=403, detail="Admins only")

过滤器

AppHeaderFilter.java

@Componentpublic class AppHeaderFilter extends OncePerRequestFilter {    @Override    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res,                                    FilterChain chain) throws ServletException, IOException {        res.setHeader("X-App", "demo");        chain.doFilter(req, res);    }}

每个请求的过滤器是一个 ASGI 中间件类，在 nexyconfig.py 中列出：

src/middlewares/app_header.py

from starlette.middleware.base import BaseHTTPMiddleware  class AppHeader(BaseHTTPMiddleware):    async def dispatch(self, request, call_next):        response = await call_next(request)        response.headers["x-app"] = "demo"        return response

nexyconfig.py

from nexy.core.models import NexyConfigModel from src.apps.app_module import AppModulefrom src.middlewares.app_header import AppHeader  class NexyConfig(NexyConfigModel):    useRouter = AppModule    useMiddlewares = [(AppHeader, {})]

仅在某些控制器之前运行的 HandlerInterceptor 是它们的守卫。

`ResponseStatusException` 和 `@ControllerAdvice`

订单控制器.java

@GetMapping("/api/orders/{id}")public Order order(@PathVariable long id) {    return orders.findById(id)        .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "No such order"));}

src/apps/orders/orders_controller.py

from nexy.decorators import Controllerfrom nexy.http import HTTPException ORDERS = {1: {"id": 1, "total": 42}}  @Controller("/api/orders/{id}")class OrderController:    async def get(self, id: int) -> dict:        if id not in ORDERS:            raise HTTPException(status_code=404, detail="No such order")        return ORDERS[id]

发送 Accept: application/json 的 API 客户端会收到 {"detail": "No such order"} 以及您提出的状态；浏览器获取 HTML 未找到页面。

百里香叶

用户页面控制器.java

@Controllerpublic class UserPageController {    @GetMapping("/users")    public String users(Model model) {        model.addAttribute("users", List.of(new User("Ada"), new User("Alan")));        return "users";    }}

模板/users.html

<ul>  <li th:each="user : ${users}" th:text="${user.name}"></li></ul>

控制器以返回 "users" 的方式返回视图：useViews 渲染 .nexy 文件，其 context 是 Model：

src/apps/users/users_view.nexy

---users: prop[list]---<ul>  {% for user in users %}  <li>{{ user.name | e }}</li>  {% endfor %}</ul>

src/apps/users/users_page_controller.py

from nexy import useViewsfrom nexy.decorators import Controller  @Controller("/users")class UsersPageController:    async def get(self):        users = [{"name": "Ada"}, {"name": "Alan"}]        return useViews("src/apps/users/users_view.nexy", context={"users": users})

th:text 转义，而 {{ }} 不转义：转义访问者用 | e 键入的内容。页面还可以保留 src/routes/ 文件，在控制器旁边提供服务。

JPA 实体和存储库

后java

@Entitypublic class Post {    @Id @GeneratedValue Long id;    String title;    boolean published;} public interface PostRepository extends JpaRepository<Post, Long> {    List<Post> findByPublishedTrue();}

该实体是一个 SQLModel 类，存储库是围绕会话的可注入服务：

src/models/post_model.py

from sqlmodel import Field, SQLModel  class Post(SQLModel, table=True):    id: int | None = Field(default=None, primary_key=True)    title: str    published: bool = False

src/apps/posts/post_repository.py

from sqlmodel import Session, select from nexy.decorators import Injectablefrom src.configs.db import enginefrom src.models.post_model import Post  @Injectable()class PostRepository:    def find_by_published_true(self) -> list[Post]:        with Session(engine) as session:            return list(session.exec(select(Post).where(Post.published)))

src/apps/posts/posts_controller.py

from nexy.decorators import Controller from .post_repository import PostRepository  @Controller("/api/posts/published")class PublishedPostsController:    def __init__(self, posts: PostRepository) -> None:        self.posts = posts     async def get(self) -> dict:        return {"titles": [post.title for post in self.posts.find_by_published_true()]}

src/apps/posts/posts_module.py

from nexy.decorators import Module from .post_repository import PostRepositoryfrom .posts_controller import PublishedPostsController  @Module()class PostsModule:    controllers = [PublishedPostsController]    providers = [PostRepository]

Flyway 或 Liquibase 迁移变为 nx migrate -m "add posts" 和 nx migrate --upgrade。请参阅数据库。

`application.properties`

春季启动	内克西
`server.port=8080`	`usePort = 8080` 在 `nexyconfig.py`
`spring.datasource.url`	`DATABASE_URL` 在 `.env`
`@CrossOrigin` / `CorsConfigurationSource`	`useCORS = {"allow_origins": [...]}`
`server.compression.enabled=true`	`useGZip = {"minimum_size": 1000}`
`springdoc.swagger-ui.path=/docs`	`useDocsUrl = "/docs"`，默认开启
`src/main/resources/static/`	`public/`，服务于 `/`

nexyconfig.py

from nexy.core.models import NexyConfigModel from src.apps.app_module import AppModule  class NexyConfig(NexyConfigModel):    useRouter = AppModule    usePort = 8080    useCORS = {"allow_origins": ["https://example.com"]}    useGZip = {"minimum_size": 1000}

执行器健康状况

应用程序属性

management.endpoints.web.exposure.include=health

健康检查是一个像任何其他控制器一样的控制器，这里是上面的 /admin/health 控制器。公共模块位于根模块中：

src/apps/health_controller.py

from nexy.decorators import Controller  @Controller("/health")class PublicHealthController:    async def get(self) -> dict:        return {"status": "UP"}

`@Async` 和 `@Scheduled`

邮件服务.java

@Asyncpublic void sendWelcome(String email) { ... }

答案后运行的工作是后台任务，作为参数：

src/apps/signup/signup_controller.py

from nexy.decorators import Controller, UseResponsefrom nexy.http import BackgroundTasks  def send_welcome(email: str) -> None: ...  @Controller("/api/signup")class SignupController:    @UseResponse(status_code=202)    async def post(self, email: str, tasks: BackgroundTasks) -> dict:        tasks.add_task(send_welcome, email)        return {"queued": True}

对于 @Scheduled 作业，运行 nx start 旁边的调度程序（例如 APScheduler）或 cron 作业。

WebSockets

EchoHandler.java

public class EchoHandler extends TextWebSocketHandler {    @Override    protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception {        session.sendMessage(message);    }}

socket 方法在其控制器的路径上打开 WebSocket：

src/apps/ws/echo_controller.py

from fastapi import WebSocket from nexy.decorators import Controller  @Controller("/ws/echo")class EchoController:    async def socket(self, websocket: WebSocket) -> None:        await websocket.accept()        await websocket.send_text(await websocket.receive_text())

客户端连接到 /ws/echo/，末尾带有斜杠。

使用 MockMvc 进行测试

HelloControllerTest.java

@WebMvcTest(HelloController.class)class HelloControllerTest {    @Autowired MockMvc mvc;     @Test    void hello() throws Exception {        mvc.perform(get("/api/hello")).andExpect(jsonPath("$.message").value("Hello"));    }}

测试/test_hello.py

from fastapi.testclient import TestClient from nexy.app import app  def test_hello():    assert TestClient(app).get("/api/hello").json() == {"message": "Hello"}

跑步

春季启动	内克西
启动.spring.io	`nx new`，使用模块化路由器
`./mvnw spring-boot:run` 使用 DevTools	`nx dev`
`./mvnw package && java -jar app.jar`	`nx build`，然后 `nx start`
`./mvnw test`	`nx test`

后续步骤

在 GitHub 上编辑

从 Spring Boot 到 Nexy

打开模块化路由器

控制器一个

@PathVariable 和 @RequestParam

@RequestBody、@Valid 和 ResponseEntity

@Service 和构造函数注入

@Configuration 类和模块

@RequestMapping 在课堂上

春季安全

过滤器

ResponseStatusException 和 @ControllerAdvice

百里香叶

JPA 实体和存储库

application.properties

执行器健康状况

@Async 和 @Scheduled

WebSockets

使用 MockMvc 进行测试

跑步

后续步骤

`@PathVariable` 和 `@RequestParam`

`@RequestBody`、`@Valid` 和 `ResponseEntity`

`@Service` 和构造函数注入

`@Configuration` 类和模块

`@RequestMapping` 在课堂上

`ResponseStatusException` 和 `@ControllerAdvice`

`application.properties`

`@Async` 和 `@Scheduled`