SuperAPI AI 工具集

maui-app-architecture

编程与开发

查看项目

更新于 10-16 06:55

技能介绍

用途

该技能面向 .NET MAUI 应用的应用级架构设计,覆盖服务、页面、ViewModel、绑定与导航的接线工作。其核心主张是:优先采用显式、可测试的架构,而不是服务定位器(service locator)模式。

主要能力

  • 依赖注入与 MauiProgram 配置:在 MauiProgram.cs 中注册依赖,页面与 ViewModel 使用构造函数注入。
  • MVVM 页面/ViewModel 接线:保持应用既有的 UI 模式,包括 XAML/MVVM、C# Markup、MauiReactor、Blazor Hybrid 或混合模式。
  • 编译绑定:在页面和数据模板中使用带 x:DataType 的编译绑定,以获得编译期类型检查、消除反射开销,并可能带来启动与滚动性能的可测量改进。
  • Shell 路由与导航:在应用启动附近一次性注册 Shell 路由,通过 Shell 路由查询参数传递导航数据,使用 GoToAsync 进行跳转。
  • trim 安全与 NativeAOT 敏感场景:在完整裁剪或 NativeAOT 场景下,优先使用 IQueryAttributable 而非 [QueryProperty]。
  • 平台 API 隔离:将平台 API 放在接口之后,使 ViewModel 保持可单元测试。

使用方式

工作流程包括:检查 MauiProgram.cs、AppShell.xaml、页面构造函数与现有 ViewModel;保持应用既有 UI 模式;在 MauiProgram.cs 中注册依赖;页面与 ViewModel 使用构造函数注入;在页面和数据模板中使用带 x:DataType 的编译绑定;在应用启动附近一次性注册 Shell 路由;通过 Shell 路由查询参数传递导航数据。

依赖注入的生命周期建议:无状态 API 客户端与数据服务使用 Singleton 或类型化 HttpClient 服务;带页面状态的 ViewModel 使用 Transient;页面使用 Transient;用户会话/状态服务若有意为应用级则使用 Singleton;按流程可释放的服务仅在应用有明确作用域边界时使用 Scoped。应避免在 MauiProgram.cs 内调用 BuildServiceProvider(),而是注册类型并让 MAUI 解析。

Shell 导航模式示例:

Routing.RegisterRoute(nameof(DetailsPage), typeof(DetailsPage));

await Shell.Current.GoToAsync($"{nameof(DetailsPage)}?id={Uri.EscapeDataString(id)}");

public sealed partial class DetailsViewModel : ObservableObject, IQueryAttributable
{
    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        if (query.TryGetValue("id", out var value) && value is string id)
        {
            Load(Uri.UnescapeDataString(id));
        }
    }
}

关于 trim 安全的 Shell 查询参数:[QueryProperty] 使用方便,但不是 trim 安全的。当涉及完整裁剪或 NativeAOT 时,应在接收页面或 ViewModel 上使用 IQueryAttributable。ApplyQueryAttributes 让解析、验证、转换与失败处理保持显式,而不是依赖基于特性的属性赋值。当值来自基于 URI 的 Shell 导航时,通过 IQueryAttributable 收到的字符串条目不会自动进行 URL 解码,使用前需显式解码,例如使用 Uri.UnescapeDataString。

编译绑定示例:

<ContentPage
    x:Class="MyApp.Views.ProductsPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:viewModels="clr-namespace:MyApp.ViewModels"
    xmlns:models="clr-namespace:MyApp.Models"
    x:DataType="viewModels:ProductsViewModel">
    <CollectionView ItemsSource="{Binding Products}">
        <CollectionView.ItemTemplate>
            <DataTemplate x:DataType="models:Product">
                <Label Text="{Binding Name}" />
            </DataTemplate>
        </CollectionView.ItemTemplate>
    </CollectionView>
</ContentPage>

从旧模式迁移的对照:DependencyService.Get<T>() 改为在 DI 中注册 T 并注入;静态服务定位器改为构造函数注入;到处使用字符串类型的 BindingContext 设置改为页面/ViewModel 注册与编译绑定;未注册的 Shell 路由字符串改为 Routing.RegisterRoute 配合常量或 nameof;ViewModel 中的平台代码改为接口抽象加平台实现。

适用场景

适用于需要设计或重构 .NET MAUI 应用架构的场景,尤其是涉及依赖注入配置、MVVM 接线、Shell 导航与查询参数传递、编译绑定,以及需要满足裁剪或 NativeAOT 要求时的导航实现。

限制

资料未提供该技能的收费、价格、平台支持范围或具体效果数据。验证清单要求:服务、页面与 ViewModel 注册一致;未引入新的服务定位器或 BuildServiceProvider() 用法;绑定到 ViewModel/模型的页面与模板具有 x:DataType;路由在使用前注册且查询值经过编码;trim 敏感或 NativeAOT 敏感的 Shell 导航使用 IQueryAttributable,且字符串 URI 查询值被显式解码;ViewModel 无需启动 MAUI 应用即可测试。