Pomelo 术语

应用逻辑服务器

• gate和connector又称为前端服务器，应用逻辑服务器是后端服务器，它完成实际的应用逻辑，并提供服务给客户端，当然客户端的请求是通过前端服务器路由过来的。
• 后端服务器之间也会通过RPC调用而有相互之间的交互，由于后端服务器不会跟客户端直接有连接，因此后端服务器只需监听它提供服务的端口即可。

主服务器 master

master加载配置文件，通过读取配置文件，启动所配置的服务器集群，并对所有服务器进行管理。

RPC调用 rpc

Pomelo中使用RPC调用进行进程间通信，在Pomelo中RPC调用分为两类：使用namespace命令空间进行区分，namespace为sys的是系统RPC调用，它对用户来说是透明的，目前Pomelo中系统RPC调用有：

• 后端服务器向前端服务器请求session会话信息
• 后端服务器通过channel推送消息时对前端服务器的RPC调用
• 前端服务器将用户请求路由给后端服务器时也是sys rpc调用

除了系统RPC调用之外，其余的由用户自定义的RPC调用属于user namespace的RPC调用，需要用户自己完成RPC服务端remote的handler代码，并由RPC客户端显式地发起调用。

路由 router

route是用来标识一个具体服务或客户端接受服务端推送消息的位置，对服务器来说，其形式一般是：chat.chatHandler.send，其中chat是服务器类型，chatHandler是chat服务器中定义的一个Handler，send则是这个Handler中的一个handler方法。

对客户端来说，其路由形式一般为onXXX，当服务端请求到达后，前端服务器会将用户客户端请求派发到后端服务器，这种派发需要一个路由函数router，可以粗略地认为router是根据用户的session以及其请求内容做一些运算后，将其映射到一个具体的应用服务器ID。

可以通过application的route调用给某一类型的服务器配置其router。若不配置的话，Pomelo会使用一个默认的router。

Pomelo默认的路由函数是使用session里面的uid字段，计算uid字段的crc32校验码，然后用这个校验码作为key，跟同类应用服务器数目取余，得到要路由到的服务器编号。注意这里有一个陷进，如果session没有绑定uid的话，此时uid字段为undefined，可能会造成所有请求都路由到同一台服务器，所以在实际开发中还是需要自己来配置router。

会话 session

Session会话是指一个客户端连接的抽象，Pomelo框架中有三个session会话的概念分别是Session、FrontendSession、BackendSession。

session会话字段结构

{
  id:<session id>//readonly
  frontendId: <frontend server id> //readonly
  uid: <bound uid> // readonly
  settings: <key-value map> //read and write
  __socket__: <raw_socket>
  __state__: <session state>
  //...
}

字段	权限	描述
id	只读	当前session会话的ID，全局唯一，自增方式来生成。
frontendId	只读	维护当前session会话的前端服务器的ID
uid	只读	当前session会话所绑定的用户ID
settings	读写	维护key-value map用来描述session会话的自定义属性
__socket__	只读	底层原生socket的引用
__state__	只读	用来指明当前session会话的生命周期状态

一个session会话一旦建立，那么id、frontendId、uid、__socket__、__state__都是确定的，都应该是只读不可写的。而settings也不应该被随意修改。

FrontendSession

因此在前端服务器中引入了FrontendSession可将其看作是一个内部session会话在前端服务器中的傀儡。

FrontendSession的字段结构

{
  id: <session id> // readonly
  frontendId: <frontend server id> // readonly
  uid: <bound uid> // readonly
  settings: <key-value map> // read and write
}

FrontendSession的作用

• 通过FrontendSession可以对settings字段进行设置值，然后通过调用FrontendSession的push()方法，将设置的settings的值同步到原始的session会话中。
• 通过FrontendSession的bind调用可以给session绑定uid
• 通过FrontendSession访问session的只读字段，不过对FrontendSession中与session中相同的只读字段的修改并不会反映到原始的session中。

BackendSession

BackendSession与FrontendSession类似，BackendSession是用于后端服务器的，可以看作是原始session的代理，其数据字段跟FrontendSession基本一致。

BackendSession是由BackendSessionService创建并维护的，在后端服务器接收到请求后，由BackendSessionService根据前端服务器RPC的参数进行创建。

服务 service

Pomelo框架有两个service服务：SessionService、BackendSessionService

• SessionService

SessionService维护所有的原始session信息，包括不可访问的字段，绑定的uid以及用户自定义的字段。

SessionService只存在于前端服务器，Session以每个客户端请求自增1的形式生成，用于管理连接Pomelo的客户端。如果在前端服务器不进行相关控制对于每个请求都会产生一个Session，就是说客户端都会在前端的服务器中的sessionService产生一个会话，值得注意的是自Pomelo0.4.x支持同一账号多处登录，所以sessionService中的session对应的是一个数组。如果对session不做任何处理的话，每刷新一次页面都会对这个session数组自增1，从暴露的API可以看出sessionService可以用于对连接在前端服务器的客户端，踢下线或利用session id直接在前端服务器发消息给客户端。

• BackendSessionService

对BackendSessionService的每次方法调用实际上都会生成一个远程过程调用，比如通过一个sid获取其BackendSession。同样对于BackendSession中字段的修改也不会反映到原始的session中，不过与FrontendSession一样，BackendSession也有push、bind、unbind调用，它们的作用与FrontendSession一样都是用来修改原始中的settings字段或绑定/解绑uid的，不同的是BackendSession的这些调用实际上都是namespace为sys的远程调用。

频道 Channel

channel可以看作是玩家ID的容器，主要用于需要广播推送消息的场景。

可以把玩家加入到一个channel中，当对这个channel推送消息时，所有加入到这个channel的玩家都会受到推送过来的消息。

一个玩家的ID可能会加入多个channel中，这样玩家就会受到其加入的channel推送过来的消息。

需要注意的时channel都时服务器本地的，应用服务器A和B并不会共享channel，也就时说在服务器A上创建的channel只能 由服务器A才能给它推送消息。

消息类型 request response notify push

Pomelo中有四种消息类型的消息分别是request、response、notify、push

• 客户端发起request请求到服务器，服务器处理后返回response响应。
• notify是客户端发给服务器的通知，也就是不需要服务器给与回复的请求。
• push是服务器主动给客户端推送消息的类型

Pomelo客户端和服务器之间的通讯方式分为三种

• request-response
  Pomelo中最场景的是Request-Response模式，客户端发送请求服务器异步响应。
  客户端的请求发送形式类似AJAX：

pomelo.request(url, msg, function(data){});

参数	描述
url	请求地址，完整地址包括三部分：服务器类型、服务端相应文件名、服务端相应方法名
msg	消息体，可为JSO格式
callback	回调函数，请求的响应会将结果放置在回调函数中返回给客户端。

• notify
  notify与request-response类似，唯一区别是客户端只负责发送消息到服务器，客户端不接收服务器的消息响应。

pomelo.notify(url, msg);

• push

push是服务器主动向客户端进行消息推送，客户端根据路由信息进行消息区分进行转发。通常游戏服务器都会发送大量此类广播。

pomelo.on(route, function(data){});

过滤器 filter

filter分为before和after两类，每个filter都可以注册多个形成一个filter链，所有客户端请求都会经过filter链进行处理。

• before filter会对请求做一些前置处理，如检查当前玩家是否已经登录，打印统计日志等。
• after filter是进行请求后置处理的地方，比如释放请求上下文的资源，记录请求总耗时等。
• after filter中不应该再出现修改响应内容的代码，因为在进入after filter前响应就已经被发送给客户端。

处理器 handler

handler是实现具体业务逻辑的地方，在请求处理流程中，handler位于before filter和after filter之间。

handler的接口声明：

handler.methodName = function(msg, session, next){
  //...
}

after filter的参数含义和before filter类似，handler处理完毕后，如果需要返回给客户端响应，可以将返回结果封装成JavaScript对象，通过next传递给后续流程。

错误处理器 error handler

error handler是一个处理全局异常的地方，可以在error handler中对处理流程中发生的异常进行集中处理，如统计错误信息、组织异常响应结果等。error handler函数是可选的，如果需要可以通过app.set()向Pomelo框架进行注册。

app.set("errorHandler", handlerFunc);
//err是前面流程中发生的异常
//resp是前面流程传递过来需要返回给客户端的响应信息
errorHandler = function(err, msg, resp, session, next){
  //...
}

组件 component

Pomelo框架是由一些松耦合的component组成，每个component完成一些功能。整个Pomelo框架可以看作是一个component容器，完成component的加载以及生命周期管理。Pomelo的核心功能都是由component完成的，每个component往往有start、afterStart、stop等调用，用来完成生命周期管理。

服务器管理 admin client、monitor、master

在对Pomelo服务器进行管理的时候，有三个概念：admin client、monitor、master

monitor

monitor运行在各个应用服务器中，它会向master注册自己，向master上报其服务器的信息，当服务器集群有变化时，会接收master推送来的变化信息，更新其服务器上下文。

master

master运行在应用服务器中，它会手机整个服务器集群的信息，有变化时会将变化推送到各个monitor。同时master还接收admin client的请求，按照admin client发出的命令，执行对应的操作，如查询整个服务器集群的状态，增加一个服务器等。

admin client

admin client独立运行自己的进程，它会发起到master的连接，然后通过对master发出请求或命令，来管理整个服务器集群。目前pomelo-cli工具就是这样的一个客户端。

服务器监控管理admin module

在Pomelo中module特指服务器监控管理模块， 与compnent类似，不过在module中实现的是监控逻辑，比如收集进程状态等。用户在使用时，可以通过application的registerAdmin注册管理模块，实现用户自己定制的监控管理功能。每个module中都会定义四种回调函数，不过都是可选的。

• masterHandler(agent, msg, cb)
  当有应用服务器给master发送监控数据时，这个回调函数会由master进程进行回调，完成应用服务器的消息处理。
• monitorHandler(agent, msg, cb)
  当有master请求应用服务器的一些监控信息时，由应用服务器进行回调，完成对maser请求的处理。
• clientHandler(agent, msg, cb)
  当由管理客户端向master请求服务器集群信息时，由master进程进行回调处理客户端的请求。
• start(cb)
  当admin module注册加载完成后，这个回调会被执行，在这里可以做一些初始化工作。

Pemolo启动流程