-
Notifications
You must be signed in to change notification settings - Fork 2
Guide
哟，各位好孩子早！这边是来给大家带路去猫王殿的不起眼的指南君。本来你们以为会有个又高又帅气的文档君来给大家带路的？他爹患了懒癌所以没把他生下来真是很遗憾呢...欸，你说就这么点路程没有带路的也没关系？据说这边可是会有那个说“宇宙最强语言”的妖怪出现的哦...喜欢从小朋友手上抢零食的小绿机器人也经常捣乱...而且还有遍布各处大大小小的...哟那位大小姐，小心那边的坑！
喵玉殿论坛使用的是曾经流行的 Discuz 程序。Discuz 官方虽然有移动客户端的支持，但是新版本已经不再适配旧版本的 X2。并且官方提供的客户端在功能、性能和外观上都差强人意。在考察了一些方案之后，我们决定以 Discuz 的官方客户端插件为基础进行修改增强（DiscuzMobile），使用 Android 原生界面构建喵玉殿的客户端程序（NyaSama）。同现在流行的移动客户端架构类似，喵玉殿客户端的运行包括后端的 API 服务器和前端界面两部分，之间主要通过 json 进行数据的传递。
客户端后端的 API 服务器实际上是作为 Discuz 论坛的一个插件存在的（可以在 source\plugin\mobile 文件夹下找到源代码）。在旧版本的 Discuz X2 程序上需要安装这个名为 mobile 的插件并启用。X3 以上的版本则已经作为内置插件存在。同 Discuz 本身一样，客户端插件也是以 php 编写的。在前端使用 http 协议以 json 的格式与插件通讯。在测试的时候实际上也可以直接从浏览器中访问插件地址得到想要的数据。比如
http://bbs.nyasama.com/forum.php?mod=viewthread&tid=50665
这个页面的数据，可以在以下地址以 json 的格式访问到
http://bbs.nyasama.com/api/mobile/index.php?module=viewthread&tid=50665
客户端通过类似的路径抓取插件提供的 json 数据并渲染呈现出来。
在 source\plugin\mobile 文件夹下包含三个目录：api（模块目录），extends（数据拓展），template（模板目录）
实际上，后端插件所起到的功能主要是对原来论坛代码的一个封装。在 source\plugin\mobile\api{版本号} 这样的文件夹下有很多的模块，然而大多数的代码都很短。基本结构都是处理一下输入（比如把 mod={模块名} 转为 module={模块名}），然后直接将论坛主程序包含进来，再把处理的结果经过设定好的数据结构拓展（extend）后以 json 输出。在 2.1 中举的两个链接的例子，运行的基本是同样的代码，得到的也是一样的数据，只是输出方式不同：前者通过模板输出为 html，在浏览器中显示；后者则是以 json 格式，传回客户端渲染。
模板目录存放的是使用手机浏览器时的模板，这边并没有修改。
插件的真正入口是 source\plugin\mobile\mobile.php 这个文件。在这个文件里定义了可以使用的模块名，并负责将请求转发给不同版本的不同模块脚本。如果在 api 文件夹里添加了新的模块，需要同时把新的模块名添加进这个文件里才能正常使用。
以下大致列出经过 新增/修改 的非官方模块（参考 DiscuzMobile 的 commits 为准）
- [chg] forumdisplay 允许获取板块图标
- [chg] profile 允许获取提醒
- [chg] viewthread 允许获取评论（X3 的新版插件已提供）
- [new] addcomment 提供添加评论的功能
- [new] morecomment 可载入更多评论（默认只载入最新的10条评论）
- [new] editpost 可编辑帖子
- [new] searching 可搜索帖子（论坛只开启了标题搜索）
- [new] threadcover 可根据 thread id 获取帖子的第一张图片缩略图（缩略图服务托管在 SAE 上）
- [chg] mythread 提供隐藏的帖子数
- [new] friendcp 可进行好友管理
- [new] topicadmin 可对帖子进行管理（高亮，置顶，删除等）
- [chg] viewthread 修复原版插件输出付费内容的 bug
以 X3 最新版本为基础的新版插件请查看这个分支（未测试）
https://github.com/NSDN/DiscuzMobile/commits/dz3v147
NyaSama 目前支持的最低 Android 版本是 4.0.3 (API 15)，master 分支使用的编译工具版本是 API 20。
因为是 Android 项目，所以 ADT 是必须下载设置的。另外，本项目使用 Android Studio 作为主要的 IDE，默认的 Gradle 作为构建工具。一些资源（比如 extra 文件夹下的图标）由 GIMP 绘制。
在不同配置的机器上使用不同版本的 Android Studio，可能会改变 .idea 文件夹里面的配置。建议在提交的时候不要提交关于这个文件夹内容的更改（这个文件夹最终应该会被移除）
项目大部分的依赖库都由 maven 上拉取。由于在第一次构建时会先去下载一个几十兆的 package，如果网络状况不好的话，可能会一直卡在第一次的构建中。建议为 Android Studio 设置好科学上网后再进行第一次构建。之后如果没有改动依赖则可以把 Android Studio 设置为 Offline 模式。
关于通常 Android 项目的个目录功能请自行参考其他材料。这边只简单介绍 app/src/main/java/com/nyasama 这个目录下的代码结构
- activity 应用主要的呈现部分。由这个文件夹下的十几个 Activity 组成（一个 Activity 大致上对应于一个显示的屏幕）
- fragment 是不同的 activity 中可重用的部分。其中有一些 fragment 在很多地方都被使用（如 CommonListFragment 被用于显示帖子列表、回复列表等等相当多的地方）
- libgdx 实现“关于”界面的代码
- util 程序各处中用到的实用类。其中 Helper 类中主要是静态的实用函数。Discuz 类中则提供了与后端 API 服务器交互的接口（参 3.3）。
- ThisApp 管理应用资源和配置等的 singleton 对象
Discuz 类封装了与后端 API 服务器的交互功能，具体包括
- API 服务器的路径，编码配置
- 将获取的 json 数据转换为方便处理的对象
- 表情图标的抓取解析（参 3.4）
- 用户状态的保存（登陆状态，uid，gid 等）
- 用于与 API 服务器交互的主要函数 execute（参 3.5）
- 其他有用的 upload, download 等函数
- 提醒和通知管理
基本过程是下载服务器上的一个 js 文件，喂给隐藏的一个 webview 之后，由 webview 以 json 形式返回相关的数据，之后再通过解析 json 得到表情名称和路径等信息。需要这么复杂的过程是由 Discuz 本身的设计导致的（似乎 Discuz 的开发人员具有把 javascript 当 php 写这样的神奇能力），对启动速度和内存占用都有影响，总之是需要优化的部分。
前面提到服务器插件以类似这样的 url 提供服务
http://bbs.nyasama.com/api/mobile/index.php?module=viewthread&tid=50665
在 Discuz 工具类中，可以以下面这样的方式来使用
Discuz.execute("viewthread", new HashMap<String, Object>(){{
// 这个 map 里面的数据会被组成到路径 url 里面
put("tid", 50665)
}}, new HashMap<String, Object>(){{
// 这个 map 里面的数据会成为 post 的内容
}}, new Response.Listener<JSONObject>() {
// 重载这个对象的 onResponse 函数来处理得到的数据
})由于回调函数是异步执行的，所以在处理数据之前可能需要确认当前 Activity 的状态
对于每个模块的功能和所需的参数，Discuz 官方并没有提供详细的文档。不过之前提过服务器插件基本上是对论坛代码的包装，输入参数实际上是直接传递给论坛代码的，那么只需要构造适合的输入参数，可是能够成功地调用论坛功能的。通过阅读论坛源代码和抓包分析，基本上论坛的大多数功能，都可以当成 API 的形式来使用。
Discuz 架构 http://faq.comsenz.com/library/
ADT (Android Development Tols) http://developer.android.com/sdk/index.html
Android Studio http://developer.android.com/tools/studio/index.html