Neo 构建鸿蒙应用【三】：实战社交应用与工程感悟

Neo 框架连载（终篇）· AI 辅助撰写

前两篇讲完了架构和机制。这一篇换个角度——不谈概念，只看代码。用一个模拟 Soul 业务场景的社交应用完整实现，验证框架在真实项目中的表现，最后分享一些工程实践中的感悟。

示例项目：EchoApp

EchoApp 是 Neo 仓库中的示例项目（examples/soul-app），模拟一款社交应用的核心功能：聊天、广场动态、匹配、用户资料等。不是 demo 级别的 HelloWorld，而是有意按照中型项目的体量来组织代码：

维度	数量
Service 总数	27
infra 层	8
business 层	12
feature 层	5
lazy 层	2
页面	10
组件	40+

选择这个体量是有原因的——太少了看不出分层的价值，太多了读起来成本太高。27 个 Service 恰好在"能看清楚全貌"和"有足够的复杂度"之间。

从零开始：AppModule 的设计思路

AppModule 是整个应用的起点，所有 27 个 Service 在这里统一声明：

export const appModule = new NeoModule('EchoApp', [
  // ===== GLOBAL_PHASE (serial, p10) — 8 infra services =====
  { tag: 'AppInitService', phase: GLOBAL_PHASE, factory: () => new AppInitService() },
  { tag: 'SecurityService', phase: GLOBAL_PHASE,
    factory: () => new SecurityService(), dependencies: ['AppInitService'] },
  { tag: 'DatabaseService', phase: GLOBAL_PHASE,
    factory: () => new DatabaseService(), dependencies: ['AppInitService'] },
  { tag: 'NetworkService', phase: GLOBAL_PHASE,
    factory: () => new NetworkService(), dependencies: ['AppInitService', 'SecurityService'] },
  { tag: 'CacheService', phase: GLOBAL_PHASE, factory: () => new CacheService() },
  { tag: 'StorageService', phase: GLOBAL_PHASE,
    factory: () => new StorageService(), dependencies: ['AppInitService'] },
  // ...

  // ===== BUSINESS_PHASE (serial, p20) — 12 business services =====
  { tag: 'AuthService', phase: BUSINESS_PHASE,
    factory: () => new AuthService(), dependencies: ['NetworkService', 'SecurityService', 'StorageService'] },
  { tag: 'UserService', phase: BUSINESS_PHASE,
    factory: () => new UserService(), dependencies: ['AuthService', 'DatabaseService'] },
  { tag: 'IMService', phase: BUSINESS_PHASE,
    factory: () => new IMService(), dependencies: ['AuthService', 'NetworkService', 'DatabaseService'] },
  { tag: 'MomentService', phase: BUSINESS_PHASE,
    factory: () => new MomentService(), dependencies: ['AuthService', 'NetworkService', 'CacheService'] },
  { tag: 'MatchService', phase: BUSINESS_PHASE,
    factory: () => new MatchService(), dependencies: ['AuthService', 'NetworkService', 'CacheService'] },
  // ...

  // ===== FEATURE_PHASE (parallel, p30) — 5 feature services =====
  { tag: 'SearchService', phase: FEATURE_PHASE,
    factory: () => new SearchService(), dependencies: ['NetworkService', 'CacheService'] },
  { tag: 'AnalyticsService', phase: FEATURE_PHASE,
    factory: () => new AnalyticsService() },
  // ...

  // ===== LAZY_PHASE (parallel, p40) — 2 lazy services =====
  { tag: 'GameService', phase: LAZY_PHASE,
    factory: () => new GameService(), dependencies: ['MatchService', 'IMService'] },
  { tag: 'StoryService', phase: LAZY_PHASE,
    factory: () => new StoryService(), dependencies: ['AuthService', 'NetworkService', 'MediaService'] },
])

设计这个文件时的思考

1. 分层的判断标准

哪些 Service 放 infra、哪些放 business，不是拍脑袋决定的。判断标准：

• infra：无业务状态，换一个应用也能用。NetworkService、CacheService、DatabaseService——它们不知道"用户"是什么概念
• business：有业务状态，和具体应用绑定。AuthService 知道 token，IMService 知道消息，MomentService 知道动态
• feature：锦上添花，应用没有它们也能跑。SearchService、AnalyticsService
• lazy：用户可能永远不会用到的功能。GameService、StoryService

2. 依赖的方向

依赖关系一定是单向的：infra ← business ← feature ← lazy。不会出现 IMService 依赖 SearchService 的情况。这不是框架强制的，而是分层的自然结果——你不会在业务层引用一个功能层的服务，因为业务层在它之前就加载了。

3. Phase 的调整是启动优化的主要手段

假设启动速度不达标，优化思路不是去改 Service 内部代码，而是调整 Phase 归属：

• MatchService 从 BUSINESS 降到 FEATURE？匹配结果不在首屏展示，可以先显示骨架屏
• EmojiService 从 BUSINESS 降到 FEATURE？表情面板不是默认展开的
• 每降一个，BUSINESS 阶段就少一个串行等待的 Service，用户更快看到首页

这种优化不需要改任何业务代码，只改 AppModule 中的 phase 字段。

一个完整的数据流：发送消息

以聊天功能为例，走一遍从用户操作到 UI 刷新的全链路。

页面层（features）

// ChatPage.ets
@Entry
@Component
struct ChatPage {
  @State messages: ChatMessage[] = []
  @State inputText: string = ''
  private imSvc?: IMService
  private unbind: (() => void) | undefined
  private conversationId: string = ''

  aboutToAppear() {
    const params = router.getParams() as ChatPageParams
    this.conversationId = params.conversationId

    this.imSvc = serviceManager.get<IMService>('IMService')!
    this.unbind = StateBinder.bind<ChatMessage[]>(
      this.imSvc.getMessagesObservable(),
      this as Object,
      'messages'
    )
    this.loadMessages()
  }

  aboutToDisappear() { this.unbind?.() }

  async loadMessages() {
    if (this.imSvc && this.conversationId) {
      this.messages = await this.imSvc.getMessages(this.conversationId)
      await this.imSvc.markAsRead(this.conversationId)
    }
  }

  // 用户点击发送
  async onSend() {
    if (this.imSvc && this.inputText.trim()) {
      await this.imSvc.sendMessage(this.conversationId, this.inputText.trim())
      this.inputText = ''
    }
  }

  build() {
    Column() {
      List() {
        ForEach(this.messages, (msg: ChatMessage) => {
          ListItem() {
            // 渲染消息气泡
          }
        })
      }
      // 输入框 + 发送按钮
    }
  }
}

页面做的事情很薄：绑定 Observable、调用 Service 方法、渲染 UI。没有网络请求、没有状态管理、没有回调地狱。

业务层（domains）

// IMService.ets
export class IMService extends Service {
  private conversationsObs = new Observable<Conversation[]>([])
  private messagesObs = new Observable<ChatMessage[]>([])

  getMessagesObservable() { return this.messagesObs }

  async sendMessage(conversationId: string, content: string): Promise<ChatMessage> {
    // 1. 业务逻辑：创建消息
    const msg = this.createMessage(conversationId, content)

    // 2. 网络：发送到服务器
    await this.networkSvc.send('/im/send', msg)

    // 3. 更新 Observable → 自动通知所有绑定的页面
    const msgs = this.messagesObs.getValue()
    this.messagesObs.setValue([...msgs, msg])

    // 4. 发送事件 → 其他 Service 可以响应
    eventBus.emit('im:messageSent', { conversationId, message: msg } as Object)

    return msg
  }
}

业务层做的事情：处理业务逻辑、协调基础设施、更新 Observable、发送事件。它不知道有哪些页面在用自己，也不知道 UI 长什么样。

基础设施层（infra）

// NetworkService.ets
export class NetworkService extends Service {
  async send(path: string, data: Object): Promise<Object> {
    // 纯技术实现：HTTP 请求、重试、超时
    // 不知道"消息"是什么，只知道 path 和 data
  }
}

基础设施层做的事情：纯技术实现。不知道业务概念，不知道 UI，甚至不知道自己在被谁调用。

完整链路

用户点击发送（ChatPage.onSend）
  → imSvc.sendMessage(convId, '你好')        // 页面调 Service
    → 创建消息对象                            // 业务逻辑
    → networkSvc.send('/im/send', msg)        // 调基础设施
    → messagesObs.setValue([...msgs, msg])    // 更新 Observable
      → StateBinder 自动写入 @State messages  // 数据驱动 UI
      → ArkUI 重新渲染消息列表                 // 用户看到新消息
    → eventBus.emit('im:messageSent')         // 通知其他 Service

页面不需要手动 this.messages = newMessages，不需要 this.$setState()，不需要 notifyDataSetChanged()。Service 调了 setValue，UI 自动刷新。

新增一个功能要改几个文件

假设产品要求新增一个"举报"功能。需要改哪些文件？

1. 定义 Service — services/feature/ReportService.ets（新建）

export class ReportService extends Service {
  async report(targetId: string, reason: string): Promise<boolean> {
    const network = this.depServices.find(s => s.tag === 'NetworkService') as NetworkService
    await network.send('/report', { targetId, reason } as Object)
    return true
  }
}

2. 注册到 AppModule — modules/AppModule.ets（加一行）

{ tag: 'ReportService', phase: FEATURE_PHASE,
  factory: () => new ReportService(), dependencies: ['NetworkService'] },

3. 页面使用 — 在需要举报的页面中

const reportSvc = serviceManager.get<ReportService>('ReportService')!
await reportSvc.report(targetId, '不适当内容')

三个文件，零耦合。不需要修改 NetworkService、不需要修改任何基类、不需要在某个全局注册表里手动添加。定义 → 注册 → 使用，流程是固定的。

工程感悟

框架是团队契约，不是技术炫耀

我说这么多有的没的，核心就一件事：如果存在一种共同约束，不是特别完美，但也不特别烂，就能产生一些价值。

精准高效沟通是特例，低效沟通是常态；层次分明是特例，层次渗透是常态；需求稳定是特例，经常变更是常态。Neo 提供的不是理想架构，而是一个团队可以共同遵守的底线。所有人定义 Service 的时候知道 init 不能做 IO，声明依赖的时候知道要看 AppModule，写页面的时候知道通过 Observable 拿数据。

这种共同约束的收益不是立竿见影的，而是在项目三个月、六个月、一年后——当新功能还在源源不断地加进来，而代码还能看懂、还能改、还能测试的时候——才会体现。

ArkTS 的限制反而帮了忙

ArkTS 比 TypeScript 严格很多：不能用 any、不能用 Record<> 的动态访问、不能省略泛型、不能 spread 对象。这些限制在初期让人头疼，但回头看，它们迫使你写出更明确的代码：

• 没有 any → 每个变量都有类型 → Service 的接口必须定义清楚
• 不能动态访问属性 → 必须用接口声明 router.getParams() 的返回值 → 页面参数有文档
• 必须显式泛型 → StateBinder.bind<T>() 一眼就知道绑的是什么类型

这些限制和 Neo 的设计理念是契合的——约束带来清晰。

结构化不是炫技

尤其在近两年 AI 编程越来越成熟的背景下，"炫技"显得越来越廉价。结构化的目的是让代码可维护、可测试、可交接，而不是展示设计模式的熟练度。

AI 时代的工程节奏

Neo 本身就是 AI 辅助开发的产物。我的判断是：AI 生成产品的速度太快了，把 IDEA 尽可能快地做出来，远比人工打磨细节的 ROI 高。

本系列文章也是这个思路——核心观点和设计决策是人定的，文字落地是 AI 做的。与其花一周打磨一篇"完美"的技术文章，不如一天发三篇把思路讲清楚，把省下来的时间投入到下一个功能、下一个项目中。

写在最后

软件是有固有生命周期的，公司和团队也有生命周期。在经济上行期软件行业的迭代都非常快，很多软件在没达到最大容积之前，公司和团队的生命周期已走到最终阶段。

这不是悲观——恰恰是因为时间有限，才更需要一个好的结构约束。让代码在你还在的时候能跑，在你走了之后别人也能接。Neo 不追求成为最好的框架，只追求成为一个不太烂的共同约束。

如果这篇文章对你有一点启发，去 GitHub 看看源码，跑一下 EchoApp 示例。觉得有用就点个 Star，有问题就提 Issue。

共勉。

---

系列文章

• 一种通用中小型基于ArkTS的鸿蒙应用开发框架（华为开发者联盟）
• Neo 构建鸿蒙应用【一】：架构困境与四层结构化设计
• Neo 构建鸿蒙应用【二】：技术路线全解
• Neo 构建鸿蒙应用【三】：实战社交应用与工程感悟（本文）

Neo 构建鸿蒙应用【二】：技术路线全解

Neo 框架连载 · AI 辅助撰写 · GitHub

上一篇建立了四层架构的宏观视图。这一篇把 Neo 的全部技术机制讲完：Service、NeoModule、ServiceManager、Phase、Observable、StateBinder、Scope。

核心思路借鉴了 JavaBean 和 IoC——Java Boy 编程梦开始的地方。

Service：最小功能单元

所有领域建模被命名为 XXXService，继承 Service 基类。一个 Service 的完整生命周期：

constructor → register → init → loginCallback → load → (WORKING)
                                                  ↑
                                    reload ← unload ← logoutCallback

基类定义

export abstract class Service implements AppPropagation {
  tag: string = this.constructor.name    // 默认用类名作标识
  context: Context | undefined
  depServices: AppPropagation[] = []     // 依赖的服务列表

  constructor(services: Service[]) {
    this.depServices = services
  }

  register = (cxt: Context) => {
    this.context = cxt
    this.init()
    // lifecycle → INITIALIZED
  }

  loginCallback = async () => {
    this.load().then(res => {
      if (res) {
        // lifecycle → WORKING
        serviceManager.refreshNode(this, this.lifecycle)
      }
    })
  }

  logoutCallback = async () => { /* unload → INITIALIZED */ }

  init() {}                                        // 初始化成员属性，不能做网络 IO
  async load(): Promise<boolean> { return true }   // 加载数据
  async unload(): Promise<boolean> { return true } // 卸载清理
  reload = () => { this.unload().then(() => this.load()) }
}

设计要点：

• register 是箭头函数属性，不是方法。ArkTS 中子类不能 override 父类的箭头函数属性，保证基类的生命周期管理不被绕过
• constructor(services: Service[]) 构造器注入，Spring 的思路
• init() 不能做网络 IO——仅用于初始化成员属性
• load() 返回 Promise<boolean>——true 表示成功，状态转为 WORKING

实际例子

// AuthService.ets
export class AuthService extends Service {
  private currentUser: UserInfo | null = null
  private token: string = ''

  constructor() { super([]) }

  init() { this.currentUser = null; this.token = '' }

  async load(): Promise<boolean> {
    const saved = await this.loadFromStorage()
    if (saved) { this.token = saved.token; this.currentUser = saved.user }
    return true
  }

  async unload(): Promise<boolean> {
    this.currentUser = null; this.token = ''
    return true
  }
}

NeoModule：Koin 式模块声明

Service 定义好了，如何组织起来？借鉴 Koin 的 module DSL 风格：

import { NeoModule, GLOBAL_PHASE, BUSINESS_PHASE } from 'neo'

const networkModule = new NeoModule('Network', [
  { tag: 'ApiService', phase: GLOBAL_PHASE, factory: () => new ApiService([]) },
  { tag: 'AuthService', phase: GLOBAL_PHASE, factory: () => new AuthService([]) },
])

const userModule = new NeoModule('User', [
  { tag: 'UserService', phase: BUSINESS_PHASE,
    factory: () => new UserService([]),
    dependencies: ['AuthService'] },
])

每个声明包含：

字段	说明
tag	服务唯一标识
phase	所属加载阶段
factory	延迟创建工厂
dependencies	依赖的其他服务 tag

模块组合：

const appModule = networkModule.merge(userModule)
// 同名声明以当前模块优先

校验（load() 时自动调用）：

const errors = appModule.validate()
// 检测缺失依赖 + 循环依赖（DFS）

ServiceManager：IoC 容器

中枢管理者，处理注册、依赖解析和生命周期。

核心流程

// EntryAbility.onCreate
serviceManager.register(this.context)          // 注入上下文
serviceManager.loadModule(appModule)            // 加载模块（校验、分组、注册）
await serviceManager.loginCallback()            // 触发多阶段启动

依赖解析

内部维护两张映射：serviceMap（tag → 实例）和 dependentMap（被谁依赖）。loginCallback 触发时递归解析依赖链——加载 Service A 之前，确保其所有依赖已 WORKING：

// ServiceManager 内部（简化）
private ensureNodeWorking(node) {
  await Promise.all(node.depServices.map(dep => this.ensureNodeWorking(dep)))
  this.invokeLogin(node)
  await this.waitForLifecycle(node.tag, ServiceLifeCycle.WORKING)
}

获取服务：

const userService = serviceManager.get<UserService>('UserService')!
const isReady = serviceManager.ready(userService)

Phase：渐进式启动

27 个 Service 不需要同时加载。

四个预定义阶段

阶段	优先级	策略	用途
GLOBAL_PHASE	10	串行等待	配置、数据库、网络、安全
BUSINESS_PHASE	20	串行等待	认证、用户、消息、通话
FEATURE_PHASE	30	并行触发	搜索、统计、主题、国际化
LAZY_PHASE	40	并行触发	小游戏、故事

策略含义：

• 串行等待（waitForComplete: true）：该阶段全部完成后才进入下一阶段
• 并行触发（waitForComplete: false）：触发后立即进入下一阶段，不等待完成

时间轴 ─────────────────────────────────────────────→

GLOBAL (串行)  ████████████████
BUSINESS (串行)                 ████████████████
FEATURE (并行)                                   ████ ← 不阻塞
LAZY (并行)                                           ██ ← 不阻塞

                     ↑ UI 可交互

启动耗时可控的核心：GLOBAL + BUSINESS 同步确保核心就绪，FEATURE + LAZY 异步不阻塞。优化手段就是把非必要 Service 从 BUSINESS 降到 FEATURE。

实战中的启动优化

我曾在实际项目中用这套机制做过启动优化（详见原文），当时 Neo 还不存在，但核心代码已经具备了 Service + Phase 的雏形。

优化成果固然可喜，但更重要的是整个结构变得可控了。因为每个 Service 的依赖关系、加载阶段、生命周期都是声明式的，我可以保证：

• 把某个 Service 从 BUSINESS 降到 FEATURE，不会导致依赖它的模块出问题——依赖解析是自动的
• 新增一个 Service 不需要改任何已有代码——在 AppModule 加一行声明即可
• 变更的影响范围是可预期的——约束由框架兜底

这不是黑盒优化，而是白盒优化。以后遇到启动性能问题，打开 AppModule 调整 Phase 归属即可——不需要重新分析依赖链，不需要画调用图，套路是固定的。

自定义阶段：

const CACHE_PHASE = createPhase({
  name: 'CACHE', priority: 25, waitForComplete: false, description: '缓存预热'
})

Observable：Service 端的数据源

Service 加载了数据，如何让页面感知变化？

朴素做法是页面直接调 Service 方法拿返回值赋给 @State——但只在初始化时有效，其他页面的数据变更不会自动刷新。

Neo 的方案是 Observable——泛型观察者容器：

export class Observable<T> {
  private value_: T
  private listeners: Set<(value: T) => void> = new Set()

  constructor(initialValue: T) { this.value_ = initialValue }
  getValue(): T { return this.value_ }

  setValue(newValue: T): void {
    if (this.value_ === newValue) return
    this.value_ = newValue
    this.notify()
  }

  onChange(listener: (value: T) => void): () => void {
    this.listeners.add(listener)
    return () => { this.listeners.delete(listener) }
  }
}

没有 Subject、没有 Operator、没有调度器。ArkTS 不支持 RxJS 那套管道，也没有必要引入。

Service 中使用

export class IMService extends Service {
  private conversationsObs = new Observable<Conversation[]>([])
  private messagesObs = new Observable<ChatMessage[]>([])

  getConversationsObservable() { return this.conversationsObs }
  getMessagesObservable() { return this.messagesObs }

  async sendMessage(conversationId: string, content: string): Promise<ChatMessage> {
    const msg = await this.doSend(conversationId, content)
    const msgs = this.messagesObs.getValue()
    this.messagesObs.setValue([...msgs, msg])  // 自动通知 UI
    return msg
  }

  async load(): Promise<boolean> {
    this.conversationsObs.setValue(await this.fetchConversations())
    return true
  }
}

模式：内部持有 Observable → getter 暴露 → setValue 触发变更。外部只能订阅，不能直接修改。

StateBinder：Service 到 @State 的桥

Observable 解决了通知问题，StateBinder 解决了写入 @State 的问题：

export class StateBinder {
  static bind<T>(
    observable: Observable<T>,
    component: Object,      // 页面组件实例
    stateKey: string        // @State 属性名
  ): () => void {
    const record = component as Record<string, Object>
    record[stateKey] = observable.getValue() as Object    // 初始化
    const unlisten = observable.onChange((newValue: T) => {
      record[stateKey] = newValue as Object               // 变更时自动写入
    })
    return unlisten
  }

  static bindAll(factories: Array<() => () => void>): () => void { /* 批量绑定 */ }
}

页面中使用

@Entry
@Component
struct ChatListPage {
  @State conversations: Conversation[] = []
  private unbind: (() => void) | undefined

  aboutToAppear() {
    const imSvc = serviceManager.get<IMService>('IMService')!
    this.unbind = StateBinder.bind<Conversation[]>(
      imSvc.getConversationsObservable(),
      this as Object,       // ArkTS 要求显式转换
      'conversations'
    )
  }

  aboutToDisappear() { this.unbind?.() }

  build() {
    List() {
      ForEach(this.conversations, (conv: Conversation) => {
        ListItem() { /* 渲染会话项 */ }
      })
    }
  }
}

注意两点 ArkTS 限制：

• this as Object 不能省略——组件的 this 类型不允许直接传给 Object 参数
• 显式泛型 <T> 不能省略——ArkTS 不支持自动推断泛型给 Record<string, Object> 赋值

批量绑定：

aboutToAppear() {
  this.unbind = StateBinder.bindAll([
    () => StateBinder.bind<Conversation[]>(imSvc.getConversationsObservable(), this as Object, 'conversations'),
    () => StateBinder.bind<ChatMessage[]>(imSvc.getMessagesObservable(), this as Object, 'messages'),
    () => StateBinder.bind<number>(matchSvc.getCountObservable(), this as Object, 'matchCount'),
  ])
}

aboutToDisappear() { this.unbind?.() }  // 一行解绑所有

Scope：页面级作用域

有些 Service 是页面专属的，页面离开时应该卸载：

import { scopeManager } from 'neo'

aboutToAppear() {
  this.scope = scopeManager.createScope('ChatPage')
  this.scope.bindTo(this)  // aboutToDisappear 时自动 close

  const chatRoomSvc = new ChatRoomService([])
  this.scope.register(chatRoomSvc)
}
// 页面销毁 → scope.close() → unload 所有注册的服务

Scope 查找机制：优先从作用域内找，找不到回退到全局 ServiceManager。scope.get<T>('ChatRoomService') 获取页面级服务，scope.getGlobal<T>('AuthService') 获取全局服务。

小结

Neo 的完整技术路线：

组件	职责
Service	功能单元，声明式生命周期
NeoModule	Koin 式模块声明，组合与校验
ServiceManager	IoC 容器，依赖解析
Phase	多阶段加载，串行/并行策略
Observable	Service 端可观察数据源
StateBinder	Service 数据 → @State 响应式桥
Scope	页面级作用域，自动卸载

下一篇是最后一篇，用 SoulApp 示例串起全链路，并分享这个框架在工程实践中的一些感悟。

---

系列文章

• 一种通用中小型基于ArkTS的鸿蒙应用开发框架（华为开发者联盟）
• Neo 构建鸿蒙应用【一】：架构困境与四层结构化设计
• Neo 构建鸿蒙应用【二】：技术路线全解（本文）
• Neo 构建鸿蒙应用【三】：实战社交应用与工程感悟

Neo 构建鸿蒙应用【一】：架构困境与四层结构化设计

Neo 框架连载 · AI 辅助撰写

在 AI 编程工具快速普及的今天，产品的试错成本大幅降低——把 IDEA 尽可能快地做出来才是最重要的，人工打磨细节和文章的 ROI 已经不高了。本系列文章均为人指导、AI 生成的内容，核心思路和设计决策来自人的判断，AI 负责快速落地。

软件工程不止编码

在鸿蒙应用开发过程中，工作内容远不止写代码。需求评审、三方 SDK 对接（鸿蒙化进度不受控时需要兜底方案）、功能测试、自动化测试、稳定性测试、CI/CD 部署……这些都是日常。

这些环节的质量，很大程度上取决于系统的初始设计。

平铺开发的典型症状

一般来说，组织沟通方式会通过系统设计表达出来——康威定律。基于 Spring 的微服务是特例，技术栈自带局部架构。但客户端不一样，尤其是鸿蒙客户端——技术栈太新，没有"自带架构"的框架可用。

没有明确设计的系统，功能基本是平铺开发，整体结构不超过三层：

• 层层耦合，处处不内聚 — 页面里直接写网络请求，网络回调里直接操作 UI
• 看似面向对象，实则面向过程 — 定义了 class，但方法之间是线性调用关系，没有职责划分
• 补丁叠补丁 — 新需求来了，再加一层 if-else，再补一个回调
• 霰弹式修改 — 一个业务变更要改七八个文件，每个文件改一两行

项目像一个穿着"百衲衣"的大胖子，某处破裂贴上胶布继续凑合用。按照 Martin Fowler 在《企业应用架构模式》中的观点：随着领域逻辑复杂度的提升，领域建模程度较低的项目，增加的工作量是近似指数级的。

三个客观现实：

1. 紧迫的任务与受限的预算 — 中小团队没有时间做"理想"的重构
2. 开发团队较低的组织程度和建模意识 — 没有框架约束，每人按自己的理解写代码
3. 增加的工作量越来越不受控 — 前两者叠加的必然结果

前些年很火的 DDD（领域驱动建模），在中小团队中培训成本高到不可能落地。但我认为最适合领域建模的软件产品是客户端而非服务器——客户端所有代码跑在同一个进程里，没有网络边界作为天然屏障，一个烂模块会影响整个应用。

两种约束

面对以上问题，我提出两种约束——不是"最佳实践"，而是划定底线：

• 约束一：相对完整的结构化设计，不能有过高的理解成本
• 约束二：功能模块的规范定义，编排层次性的启动顺序

这两种约束的具体落地就是 Neo 框架。下面展开约束一。

四层结构化架构

┌─────────────────────────────────────┐
│            entry（应用入口）          │
│    页面入口 / 路由 / 一多方案适配      │
├─────────────────────────────────────┤
│           features（功能页面层）       │
│    只处理页面交互，不处理数据逻辑       │
├─────────────────────────────────────┤
│         domains（领域建模层）          │
│    数据获取、业务逻辑、跨功能服务       │
├─────────────────────────────────────┤
│           infra（基础设施层）          │
│    无状态，可迁移，三方 SDK            │
└─────────────────────────────────────┘

entry — 应用入口

功能聚集层。入口页面、路由、一多方案适配，既是所有页面和功能的门面，也是构建的集合。按照项目实际情况可以选择一多方案适配或多端独立方式适配。

features — 功能模块页面层

通过领域建模获取数据，自身只处理页面交互逻辑，不处理服务器、硬盘的数据。上层页面是相对抽象的，聚合内部功能的；下层负责具体功能。

domains — 领域建模层

这里并不一定要使用领域驱动建模的概念。具体业务领域是容易区分的，但公共能力很容易渗透到全局。上层的责任是编排各个领域，而非公共能力。

例如用户鉴权，很容易被拆分成用户数据结构在最下层、登录逻辑在上层。而更合理的情况是：上层有自己的值对象，登录鉴权的逻辑和数据结构内聚，完成这个过程后通知全局，自上而下分发状态。

infra — 基础设施层

最简单的理解就是当做二方和三方，尽可能按照可迁移到其他项目的思路设计。重点考虑无状态和可迁移——不是真的要迁移，而是最干净的基础设施是完全无状态的。

状态指的是由使用、登录获取的数据及其传递依赖。例如从个人登录信息 → 登录会议 SDK → 处理会议数据，这里就是状态的传递。无状态的模块不可以主动获取状态，需要数据应由调用方传入。

层级边界渗透

企业的最初和最终的目的是盈利，项目最初和最终的定位是工具。设计原则不管是 SOLID 还是七原则，都是局部"术"的层面，而真实的世界是混沌的。各层之间的设计都应考虑层级边界渗透的情况。

entry ↔ 下层

页面是相对抽象的，聚合内部功能的，主要是整体页面框架、路由、一多适配。与下层的边界较好区分。

features ↔ 下层

features → domains：页面逻辑还是业务逻辑？通常的经验是页面操作驱动业务逻辑，业务数据驱动页面逻辑。例如网络通话场景，通话状态的转移是 SDK 数据的变化，页面也会根据这个数据变化。但页面不存在通话就不存在了吗？现在的大部分通话场景都已支持悬浮窗，通话的数据要独立在自己的领域建模中。

features → infra：具体功能页面还是组件？某个组件是否需要复用，复用即在下层。

domains ↔ infra

渗透的重灾区。在没有建模的项目中，事实上的基础模块很多都是带业务状态的。这种很难改——改完容易出错，出错容易背锅，写的越多越错。逻辑的编排需要分清是通用逻辑还是业务逻辑，这部分可以适当用一些设计模式。

Neo 的四层在代码中的样子

以 Neo 的 SoulApp 示例为例：

entry/src/main/ets/
├── pages/                    # features — 页面交互
│   ├── IndexPage.ets         #   首页
│   ├── ChatPage.ets          #   聊天
│   ├── ExplorePage.ets       #   发现
│   └── ...
├── services/                 # domains — 领域服务
│   ├── business/             #   核心业务 (12个)
│   │   ├── AuthService       #   认证
│   │   ├── ChatService       #   聊天
│   │   └── ...
│   ├── feature/              #   功能服务 (5个)
│   └── lazy/                 #   非关键服务 (2个)
├── services/infra/           # infra — 基础设施 (8个)
│   ├── NetworkService
│   ├── DatabaseService
│   ├── CacheService
│   └── ...
├── modules/                  # entry — 模块注册
│   └── AppModule.ets         #   所有 Service 的编排入口
└── data/                     # 跨层数据模型
    ├── Models.ets
    └── MockData.ets

下一篇将展开约束二：Service、NeoModule、ServiceManager 和 Phase 如何实现模块化服务编排与渐进式启动。

---

系列文章

• 一种通用中小型基于ArkTS的鸿蒙应用开发框架（华为开发者联盟）
• Neo 构建鸿蒙应用【一】：架构困境与四层结构化设计（本文）
• Neo 构建鸿蒙应用【二】：技术路线全解
• Neo 构建鸿蒙应用【三】：实战社交应用与工程感悟