Mars - 微信官方的跨平台跨业务的终端基础组件
zhsuppervi
8年前
<h2>Mars</h2> <p>Mars is a cross-platform infrastructure component developed by WeChat Mobile Team.</p> <p style="text-align:center"><img src="https://simg.open-open.com/show/35ea472c1f50029e8a2f17ce4dc262b5.png"></p> <ul> <li>comm：common library, including socket, thread, message queue, coroutine, etc.</li> <li>xlog：a reliable log component with high-performance.</li> <li>SDT： a network detection component.</li> <li>STN： a signalling network component, the major part of Mars.</li> </ul> <h2>Samples</h2> <p>Start with sample usagehere</p> <h2>Getting started</h2> <p>ChooseAndroidoriOS/OS X</p> <h3>Android</h3> <p>You can use eithermars-wrapperormars-core. We recommend you to use mars-wrapper if only sample is needed, while mars-core is preferred to be used in your app.</p> <p>mars-wrapper</p> <p>Add dependencies by adding the following lines to your app/build.gradle.</p> <pre> <code class="language-java">dependencies { compile 'com.tencent.mars:mars-wrapper:1.1.3' }</code></pre> <p>OR</p> <p>mars-core</p> <p>Add dependencies by adding the following lines to your app/build.gradle.</p> <pre> <code class="language-java">dependencies { compile 'com.tencent.mars:mars-core:1.1.3' }</code></pre> <p>If you read here, make sure you have added dependencies of mars-wrapper or mars-core.</p> <p>Xlog Init</p> <p>Initialize Xlog when your app starts. Remember to use an exclusive folder to save the log files, no other files is acceptable in the folder since they would be removed by the cleansing function in Xlog automatically.</p> <p>When multiple processes is used in your app, make sure that each process owns its exclusive log file.</p> <pre> <code class="language-java">System.loadLibrary("stlport_shared"); System.loadLibrary("marsxlog"); final String SDCARD = Environment.getExternalStorageDirectory().getAbsolutePath(); final String logPath = SDCARD + "/marssample/log"; //init xlog if (BuildConfig.DEBUG) { Xlog.appenderOpen(Xlog.LEVEL_DEBUG, Xlog.AppednerModeAsync, "", logPath, "MarsSample"); Xlog.setConsoleLogOpen(true); } else { Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppednerModeAsync, "", logPath, "MarsSample"); Xlog.setConsoleLogOpen(false); } Log.setLogImp(new Xlog());</code></pre> <p>Uninitialized Xlog when your app exits</p> <pre> <code class="language-java">Log.appenderClose();</code></pre> <p>STN Init</p> <p>If you add dependencies of mars-core to your project, you need initialize and uninitialized STN.</p> <p>Initialize STN before you use it</p> <pre> <code class="language-java">// set callback AppLogic.setCallBack(stub); StnLogic.setCallBack(stub); SdtLogic.setCallBack(stub); // Initialize the Mars PlatformComm Mars.init(getApplicationContext(), new Handler(Looper.getMainLooper())); // Initialize the Mars StnLogic.setLonglinkSvrAddr(profile.longLinkHost(), profile.longLinkPorts()); StnLogic.setShortlinkSvrAddr(profile.shortLinkPort()); StnLogic.setClientVersion(profile.productID()); Mars.onCreate(true); BaseEvent.onForeground(true); StnLogic.makesureLongLinkConnected();</code></pre> <p>Firstly, you should call the setCallBack interface, and secondly, the Mars.init. Then, to initialize the Mars, there is to need to strictly follow the orders of the four commands. Finally, after Mars are initialized, onForeground and makesureLongLinkConnect can be called.</p> <p>Destroy STN or exit your app:</p> <pre> <code class="language-java">Mars.onDestroy();</code></pre> <p>Event Change</p> <p>Network change:</p> <pre> <code class="language-java">BaseEvent.onNetworkChange()</code></pre> <p>If you add dependencies of mars-wrapper to your project, you just need initialize STN and no need uninitialized.</p> <pre> <code class="language-java">MarsServiceProxy.init(this, getMainLooper(),null);</code></pre> <p>No matter which way of dependencies you used, you must pay attention to these.</p> <p>The state (background or foreground) of app is changed:</p> <pre> <code class="language-java">BaseEvent.onForeground(boolean);</code></pre> <p>The account of app is changed:</p> <pre> <code class="language-java">StnLogic.reset();</code></pre> <p>If you want to modify the encryption algorithm of Xlog, the packer/unpacker of longlink/shortlink, or you want to define the other components by yourself, referhere</p> <h3>iOS/OS X</h3> <p>Compile</p> <pre> <code class="language-java">python build_apple.py</code></pre> <p>Add mars.framework as a dependency of your project.</p> <p>Xlog Init</p> <p>Initialize Xlog when your app starts. Remember to use an exclusive folder to save the log files, no other files is acceptable in the folder since they would be removed by the cleansing function in Xlog automatically.</p> <pre> <code class="language-java">NSString* logPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingString:@"/log"]; // set do not backup for logpath const char* attrName = "com.apple.MobileBackup"; u_int8_t attrValue = 1; setxattr([logPath UTF8String], attrName, &attrValue, sizeof(attrValue), 0, 0); // init xlogger #if DEBUG xlogger_SetLevel(kLevelDebug); appender_set_console_log(true); #else xlogger_SetLevel(kLevelInfo); appender_set_console_log(false); #endif appender_open(kAppednerAsync, [logPath UTF8String], "Test");</code></pre> <p>Uninitialized xlog in function "applicationWillTerminate"</p> <pre> <code class="language-java">appender_close();</code></pre> <p>STN Init</p> <p>Initialize STN before you use it:</p> <pre> <code class="language-java">- (void)setCallBack { mars::stn::SetCallback(mars::stn::StnCallBack::Instance()); mars::app::SetCallback(mars::app::AppCallBack::Instance()); } - (void) createMars { mars::baseevent::OnCreate(); } - (void)setClientVersion:(UInt32)clientVersion { mars::stn::SetClientVersion(clientVersion); } - (void)setShortLinkDebugIP:(NSString *)IP port:(const unsigned short)port { std::string ipAddress([IP UTF8String]); mars::stn::SetShortlinkSvrAddr(port, ipAddress); } - (void)setShortLinkPort:(const unsigned short)port { mars::stn::SetShortlinkSvrAddr(port); } - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port debugIP:(NSString *)IP { std::string ipAddress([string UTF8String]); std::string debugIP([IP UTF8String]); std::vector<uint16_t> ports; ports.push_back(port); mars::stn::SetLonglinkSvrAddr(ipAddress,ports,debugIP); } - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port { std::string ipAddress([string UTF8String]); std::vector<uint16_t> ports; ports.push_back(port); mars::stn::SetLonglinkSvrAddr(ipAddress,ports); } - (void)reportEvent_OnForeground:(BOOL)isForeground { mars::baseevent::OnForeground(isForground); } - (void)makesureLongLinkConnect { mars::stn::MakesureLonglinkConnected(); }</code></pre> <p>Firstly, you should call the setCalBack interface, and secondly, the Mars.init. Then, to initialize the Mars, there is to need to strictly follow the orders of the four commands. Finally, after Mars are initialized, onForeground and makesureLongLinkConnect can be called.</p> <p>If you want to destroy STN or exit App:</p> <pre> <code class="language-java">- (void)destroyMars { mars::baseevent::OnDestroy(); }</code></pre> <p>Event Change</p> <p>When the App's state of background or foreground is changed:</p> <pre> <code class="language-java">- (void)reportEvent_OnForeground:(BOOL)isForeground { mars::baseevent::OnForeground(isForground); }</code></pre> <p>Network change:</p> <pre> <code class="language-java">- (void)reportEvent_OnNetworkChange { mars::baseevent::OnNetworkChange(); }</code></pre> <h2>Support</h2> <p>Any problem?</p> <ol> <li>Learn more frommars/sample.</li> <li>Read thesource code.</li> <li>Read thewiki orFAQ for help.</li> <li>Contact us for help.</li> </ol> <h2>Contributing</h2> <p>For more information about contributing issues or pull requests, see our Mars Contributing Guide .</p> <h2>License</h2> <p>Mars is under the MIT license. See theLICENSE file for details.</p> <h2>Mars</h2> <p>Mars 是微信官方的跨平台跨业务的终端基础组件。</p> <p style="text-align:center"><img src="https://simg.open-open.com/show/b84339a36ff3f67c2e6073e929ea5329.png" alt="Mars - 微信官方的跨平台跨业务的终端基础组件" width="550" height="360"></p> <ul> <li>comm：可以独立使用的公共库，包括 socket、线程、消息队列、协程等；</li> <li>xlog：高可靠性高性能的运行期日志组件；</li> <li>SDT： 网络诊断组件；</li> <li>STN： 信令分发网络模块，也是 Mars 最主要的部分。</li> </ul> <h2>Samples</h2> <p>sample 的使用请参考这里</p> <h2>Getting started</h2> <p>接入Android或者iOS/OS X</p> <h3>gradle 接入我们提供了两种接入方式：mars-wrapper或者mars-core。如果你只是想做个 sample 推荐使用 mars-wrapper，可以快速开发；但是如果你想把 mars 用到你的 app 中的话，推荐使用 mars-core，可定制性更高。</h3> <p>mars-wrapper</p> <p>在 app/build.gradle 中添加 mars-wrapper 的依赖：</p> <pre> <code class="language-java">dependencies { compile 'com.tencent.mars:mars-wrapper:1.1.3' }</code></pre> <p>或者</p> <p>mars-core</p> <p>在 app/build.gradle 中添加 mars-core 的依赖：</p> <pre> <code class="language-java">dependencies { compile 'com.tencent.mars:mars-core:1.1.3' }</code></pre> <p>接着往下操作之前，请先确保你已经添加了 mars-wrapper 或者 mars-core 的依赖</p> <p>Xlog Init</p> <p>在程序启动加载 Xlog 后紧接着初始化 Xlog。但要注意如果你的程序使用了多进程，不要把多个进程的日志输出到同一个文件中，保证每个进程独享一个日志文件。而且保存 log 的目录请使用单独的目录，不要存放任何其他文件防止被 xlog 自动清理功能误删。</p> <pre> <code class="language-java">System.loadLibrary("stlport_shared"); System.loadLibrary("marsxlog"); final String SDCARD = Environment.getExternalStorageDirectory().getAbsolutePath(); final String logPath = SDCARD + "/marssample/log"; //init xlog if (BuildConfig.DEBUG) { Xlog.appenderOpen(Xlog.LEVEL_DEBUG, Xlog.AppednerModeAsync, "", logPath, "MarsSample"); Xlog.setConsoleLogOpen(true); } else { Xlog.appenderOpen(Xlog.LEVEL_INFO, Xlog.AppednerModeAsync, "", logPath, "MarsSample"); Xlog.setConsoleLogOpen(false); } Log.setLogImp(new Xlog());</code></pre> <p>程序退出时关闭日志：</p> <pre> <code class="language-java">Log.appenderClose();</code></pre> <p>STN Init</p> <p>如果你是把 mars-core 作为依赖加入到你的项目中的话，你需要显式的初始化和反初始化 STN</p> <p>在使用 STN 之前进行初始化</p> <pre> <code class="language-java">// set callback AppLogic.setCallBack(stub); StnLogic.setCallBack(stub); SdtLogic.setCallBack(stub); // Initialize the Mars PlatformComm Mars.init(getApplicationContext(), new Handler(Looper.getMainLooper())); // Initialize the Mars StnLogic.setLonglinkSvrAddr(profile.longLinkHost(), profile.longLinkPorts()); StnLogic.setShortlinkSvrAddr(profile.shortLinkPort()); StnLogic.setClientVersion(profile.productID()); Mars.onCreate(true); BaseEvent.onForeground(true); StnLogic.makesureLongLinkConnected();</code></pre> <p>初始化顺序不一定要严格遵守上述代码的顺序，但在初始化时首先要调用 setCallBack 接口 (callback 文件的编写可以参考 demo)，再调用 Mars.init，最后再调用onForeground 和 makesureLongLinkConnect，中间顺序可以随意更改。 注意：STN 默认是后台，所以初始化 STN 后需要主动调用一次 BaseEvent.onForeground(true)</p> <p>需要释放 STN 或者退出程序时:</p> <pre> <code class="language-java">Mars.onDestroy();</code></pre> <p>Event Change</p> <p>网络切换时:</p> <pre> <code class="language-java">BaseEvent.onNetworkChange()</code></pre> <p>如果你是把 mars-wrapper 作为依赖加入到你的项目中，你只需要显式的初始化 STN，不需要反初始化(因为 mars-wrapper 会进行反初始化)</p> <pre> <code class="language-java">MarsServiceProxy.init(this, getMainLooper(),null);</code></pre> <p>不管你是使用 mars-wrapper 还是 mars-core，你都需要特别注意以下事件：</p> <p>前后台切换:</p> <pre> <code class="language-java">BaseEvent.onForeground(boolean);</code></pre> <p>应用的账号信息更改:</p> <pre> <code class="language-java">StnLogic.reset();</code></pre> <p>编译</p> <pre> <code class="language-java">python build_apple.py</code></pre> <p>把 mars.framework 作为依赖加入到你的项目中</p> <p>Xlog Init</p> <p>在程序启动加载 Xlog 后紧接着初始化 Xlog。但要注意保存 log 的目录请使用单独的目录，不要存放任何其他文件防止被 xlog 自动清理功能误删。</p> <pre> <code class="language-java">NSString* logPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0] stringByAppendingString:@"/log"]; // set do not backup for logpath const char* attrName = "com.apple.MobileBackup"; u_int8_t attrValue = 1; setxattr([logPath UTF8String], attrName, &attrValue, sizeof(attrValue), 0, 0); // init xlogger #if DEBUG xlogger_SetLevel(kLevelDebug); appender_set_console_log(true); #else xlogger_SetLevel(kLevelInfo); appender_set_console_log(false); #endif appender_open(kAppednerAsync, [logPath UTF8String], "Test");</code></pre> <p>在函数 "applicationWillTerminate" 中反初始化 Xlog</p> <pre> <code class="language-java">appender_close();</code></pre> <p>STN Init</p> <p>在你用 STN 之前初始化：</p> <pre> <code class="language-java">- (void)setCallBack { mars::stn::SetCallback(mars::stn::StnCallBack::Instance()); mars::app::SetCallback(mars::app::AppCallBack::Instance()); } - (void) createMars { mars::baseevent::OnCreate(); } - (void)setClientVersion:(UInt32)clientVersion { mars::stn::SetClientVersion(clientVersion); } - (void)setShortLinkDebugIP:(NSString *)IP port:(const unsigned short)port { std::string ipAddress([IP UTF8String]); mars::stn::SetShortlinkSvrAddr(port, ipAddress); } - (void)setShortLinkPort:(const unsigned short)port { mars::stn::SetShortlinkSvrAddr(port); } - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port debugIP:(NSString *)IP { std::string ipAddress([string UTF8String]); std::string debugIP([IP UTF8String]); std::vector<uint16_t> ports; ports.push_back(port); mars::stn::SetLonglinkSvrAddr(ipAddress,ports,debugIP); } - (void)setLongLinkAddress:(NSString *)string port:(const unsigned short)port { std::string ipAddress([string UTF8String]); std::vector<uint16_t> ports; ports.push_back(port); mars::stn::SetLonglinkSvrAddr(ipAddress,ports); } - (void)reportEvent_OnForeground:(BOOL)isForeground { mars::baseevent::OnForeground(isForground); } - (void)makesureLongLinkConnect { mars::stn::MakesureLonglinkConnected(); }</code></pre> <p>初始化顺序不一定要严格遵守上述代码的顺序，但在初始化时首先要调用 setCallBack 接口 (callback 文件的编写可以参考 demo)，再调用 Mars.init，最后再调用 onForeground 和 makesureLongLinkConnect，中间顺序可以随意更改。 注意：STN 默认是后台，所以初始化 STN 后需要主动调用一次 BaseEvent.onForeground(true)</p> <p>需要释放 STN 或者退出程序时:</p> <pre> <code class="language-java">- (void)destroyMars { mars::baseevent::OnDestroy(); }</code></pre> <p>Event Change</p> <p>前后台切换时:</p> <pre> <code class="language-java">- (void)reportEvent_OnForeground:(BOOL)isForeground { mars::baseevent::OnForeground(isForeground); }</code></pre> <p>网络切换时：</p> <pre> <code class="language-java">- (void)reportEvent_OnNetworkChange { mars::baseevent::OnNetworkChange(); }</code></pre> <h2>Support</h2> <p>还有其他问题？</p> <ol> <li>参看mars/sample.</li> <li>阅读源码.</li> <li>阅读wiki 或者FAQ</li> <li>联系我们.</li> </ol> <h2>Contributing</h2> <p>关于 Mars 分支管理、issue 以及 pr 规范,</p> <p> </p> <p> </p>