# lifecycle

Controller 是服务退出通知入口，不管理具体数据库、租约或后台任务。生成项目已经将它接入 svc 与 main，业务在 svc 调用 `c.RequestShutdown(err)` 即可，见 [项目指南](../PROJECT.md#依赖主动申请退出)。

手写服务也可组合现有 App：

```go
control := lifecycle.New(ctx)
defer control.RequestShutdown(nil)

// 在依赖的故障回调中调用，不阻塞等待排空。
control.RequestShutdown(cause)

// RunContext 会观察到已发生的退出通知，不必等监听成功才能通知。
err := app.RunContext(control.Context())
```

实际使用时 App 和依赖通常先初始化，再由并发监控回调请求退出。资源在 HTTP 排空完成后由调用方关闭，并读取 `control.Err()` 合并清理期间报告的首个故障。通知本身不会关闭资源、执行 os.Exit 或发送操作系统信号。

`RequestShutdown(nil)` 表示正常停止，非空 error 表示故障。Controller 保留首个非空故障，重复调用和并发调用安全。`Cause(ctx)` 将符合 errors.Is(err, context.Canceled) 的取消原因视为正常停止（包含新版 Go 的信号原因），保留其他取消原因和 DeadlineExceeded。显式 RequestShutdown(err) 上报的非空错误始终由 Controller.Err 保留，包括包装 context.Canceled 的错误。App.RunContext、ServeContext、RunWith 均保留这些异常原因，与网络适配器无关。