添加更多注释,优化jar包

ROOT/WEB-INF/web.xml

@@ -28,12 +28,12 @@
 	<filter-mapping>
 		<filter-name>nutz</filter-name>
 		<url-pattern>/*</url-pattern>
-		<dispatcher>REQUEST</dispatcher>
+		<dispatcher>REQUEST</dispatcher> <!-- 这基本上是标准配置了,否则forward视图不会通过这个拦截器, J2EE的知识 -->
 		<dispatcher>FORWARD</dispatcher>
 	</filter-mapping>
 
 	<listener>
-		<listener-class>org.nutz.mvc.NutSessionListener</listener-class>
+		<listener-class>org.nutz.mvc.NutSessionListener</listener-class> <!-- 监视scope=session的IocBean的生命管理,不建议使用 -->
 	</listener>
 
 	<error-page>

ROOT/js/index.js

@@ -4,7 +4,7 @@ $(function() {
     var questionTagsStr = '<p></p>';
     var html = '';
 
-    $.get('./question/query/list', function(data) {
+    $.get('./question/query/list.json', function(data) {
         if (data['ok']) {
             $.each(data['data']['data'], function (index, value) {
                 html = String.format(questionInfoStr, value['user']['id'], value['createdAt']);

src/org/nutz/ngqa/Helpers.java

@@ -7,6 +7,7 @@
 
 public class Helpers {
 
+	/**生成Question详情页的完整URL*/
 	public static String makeQuestionURL(Question question) {
 		HttpServletRequest req = Mvcs.getReq();
 		String reqURL = req.getRequestURL().toString();

src/org/nutz/ngqa/MainModule.java

@@ -12,14 +12,15 @@
 import org.nutz.ngqa.mvc.SmartViewMaker;
 import org.nutz.web.ajax.AjaxViewMaker;
 
-@Modules(scanPackage=true)
-@IocBy(args = {	"*org.nutz.ioc.loader.json.JsonLoader",
-		"ioc/",
-		"*org.nutz.ioc.loader.annotation.AnnotationIocLoader",
-		"org.nutz.ngqa"}, type = ComboIocProvider.class)
-@Ok("ajax")
-@Fail("ajax")
-@Views({AjaxViewMaker.class,SmartViewMaker.class})
-@SetupBy(NgqaSetup.class)
-@UrlMappingBy(value=EnhanceUrlMapping.class)
+/**主模块,主要功能就是项目的整体配置*/
+@Modules(scanPackage=true) //扫描当前类所在的package及子package中所有包含@At方法的类,作为模块类
+@IocBy(args = {	//配置Ioc容器
+		"*org.nutz.ioc.loader.json.JsonLoader","ioc/", //扫描ioc文件夹中的js文件,作为JsonLoader的配置文件
+		"*org.nutz.ioc.loader.annotation.AnnotationIocLoader","org.nutz.ngqa"}, 
+		type = ComboIocProvider.class) //这里用到了复合Ioc加载提供器,因为本项目同时使用了js和注解作为Ioc的配置方式
+@Ok("ajax") //配置默认视图,这里的ajax视图,是nutz-web项目额外提供的,为Ajax请求提供统一的响应格式
+@Fail("ajax") //配置失败视图,只有抛异常,才会走这个视图的,无其他方式,这种视图,一般就是接受一个异常对象
+@Views({AjaxViewMaker.class,SmartViewMaker.class}) //注册私有的ViewMaker,这里注册的是支持ajax和smart的两个ViewMaker
+@SetupBy(NgqaSetup.class) //提供一个Setup接口的实现,在项目启动/关闭时执行一些逻辑
+@UrlMappingBy(value=EnhanceUrlMapping.class) //UrlMapping能拿到很多Action映射方面的信息,所以,继承默认实现,获取自己需要的逻辑(主要Auth管理)
 public class MainModule {}

src/org/nutz/ngqa/NgqaSetup.java

@@ -19,6 +19,7 @@
 
 public class NgqaSetup implements Setup {
 
+	/**NutzMvc正常启动后就会执行这个方法,你可以认为所有东西都已经准备好了,你可以做一些额外的逻辑,例如启动某些后台线程*/
 	public void init(NutConfig config) {
 		CommonMongoService commons = config.getIoc().get(CommonMongoService.class, "commons");
 		MongoDao dao = commons.dao();
@@ -58,7 +59,8 @@ public void init(NutConfig config) {
 		}
 	}
 
+	/**项目关闭时执行的逻辑*/
 	public void destroy(NutConfig config) {
-
+		//暂时无任何操作
 	}
 }

src/org/nutz/ngqa/api/Ngqa.java

@@ -2,6 +2,7 @@
 
 public class Ngqa {
 
+	/**这里标记的是当前项目的Api版本,为以后的升级服务所预留的*/
 	public static String apiVersion() {
 		return "1";
 	}

src/org/nutz/ngqa/bean/App.java

@@ -2,6 +2,7 @@
 
 import java.util.Date;
 
+import org.nutz.json.JsonField;
 import org.nutz.mongo.annotation.Co;
 import org.nutz.mongo.annotation.CoField;
 import org.nutz.mongo.annotation.CoId;
@@ -16,7 +17,8 @@ public class App  implements Freshable{
 	@CoField
 	private String name;
 	@CoField
-	private String key;
+	@JsonField(ignore=true) //不允许直接传出去
+	private transient String key;
 	@CoField
 	private boolean active;
 	@CoField

src/org/nutz/ngqa/module/AddonModule.java

@@ -21,14 +21,15 @@
 import com.mongodb.DBCollection;
 import com.mongodb.DBCursor;
 
-@IocBean
-@InjectName
-@Ok("void")
-@Fail("http:500")
-@Filters()
+@IocBean //声明为一个Ioc的bean
+@InjectName //这是module类被识别为IocBean的一个桥. 反正你就加上吧,呵呵
+@Ok("void") //不对响应做任何修改的VoidView
+@Fail("http:500") //出错就直接跑errorPage 500了,呵呵
+@Filters() //覆盖主模块的Filters设置,因为本模块的所有方法,都允许直接访问
 public class AddonModule {
 
-	@At("/sitemap")
+	/**生成google所读取的sitemap,方便google索引本站*/
+	@At("/sitemap") //google实际访问的URI是 /sitemap.xml , 不过@At里面的值是绝对不能后缀的,因为它只会去匹配去除后缀的URI
 	@Ok("void")
 	public void sitemap(HttpServletRequest req, HttpServletResponse resp) throws IOException {
 		DBCursor cur = questionColl.find(new BasicDBObject(), new BasicDBObject("updateAt", 1)).sort(new BasicDBObject("createAt", -1));
@@ -50,8 +51,9 @@ public void sitemap(HttpServletRequest req, HttpServletResponse resp) throws IOE
 		writer.write(urlset.toString());
 	}
 
+	/**全文输出,方便定义*/
 	@At("/rss")
-	@Ok("->:/question/query/list.rss?pageSize=100")
+	@Ok("->:/question/query/list.rss?pageSize=100") //内部重定向视图,会重新跑一次流程,记得翻阅web.xml的相应配置哦
 	public void rss() {
 	}
 

src/org/nutz/ngqa/module/AdminModule.java

@@ -19,6 +19,7 @@
 
 import com.mongodb.BasicDBObject;
 
+/**管理模块,现在功能还很少*/
 @IocBean
 @InjectName
 @Ok("ajax")
@@ -28,9 +29,10 @@ public class AdminModule {
 	@Inject("java:$commons.dao()")
 	private MongoDao dao;
 
+	/**刷新权限数据*/
 	@At("/admin/role/refresh")
 	@Filters({@By(type=ActionFilter.class, args={"ioc:authFilter"})})
-	@Auth("role.refresh")
+	@Auth("role.refresh") //当前方法的权限设置,与上面的ActionFilter所对应
 	public void refreshRoleCache(){
 		Map<String, Role> roles = new HashMap<String, Role>();
 		for(Role role : dao.find(Role.class, new BasicDBObject(), null)) {

src/org/nutz/ngqa/module/AppModule.java

@@ -32,18 +32,19 @@
 
 @IocBean
 @InjectName
-@Filters()
+@Filters() //覆盖主模块的Filters设置,因为本模块的操作,均自行校验权限
 public class AppModule {
 
-	@Inject
+	@Inject//注入一个bean,是@Inject("refer:commons")的简写
 	private CommonMongoService commons;
 
-	@Inject("java:$commons.coll('systemconfig')")
+	@Inject("java:$commons.coll('systemconfig')") //可以调用方法来获取需要注入的内容的
 	private DBCollection systemconfigColl;
 
 	@Inject("java:$commons.dao()")
 	private MongoDao dao;
 
+	//这个是整个系统的最高权限,root用户,的登录入口
 	@At("/user/login/root")
 	@Ok(">>:/index.jsp")
 	public Object loginAsRoot(@Param("key") String key, HttpSession session) {
@@ -58,13 +59,17 @@ public Object loginAsRoot(@Param("key") String key, HttpSession session) {
 			return new HttpStatusView(403);
 	}
 
+	// app的登录入口.设计这个,是因为服务器端不单单面向Web,同时是个OpenAPI,允许通过其他方式访问该系统
+	// app无法通过OAuth授权来登录,因为不是浏览器,所以做这个入口,供app登录,然后再切换到其他用户.app如果要切换到某个用户,那么,这个用户必须授权给app(通过检查authedApp属性).
 	@At("/user/login/app")
 	@Ok("ajax")
 	public Object appLogin(@Param("appId") String appId, HttpSession session)
 			throws Exception {
 		if (appId != null) {
-			App app = dao.findOne(App.class, new BasicDBObject("_id", appId));
+			App app = dao.findById(App.class, appId);
 			if (app != null) {
+				if (!app.isActive())
+					return Ajax.fail().setData("app isn't active!");
 				String value = UUID.randomUUID().toString() + "_"
 						+ Math.random();
 				session.setAttribute("app.token", value);
@@ -80,6 +85,7 @@ public Object appLogin(@Param("appId") String appId, HttpSession session)
 		return Ajax.fail();
 	}
 
+	//为了避免app直接发送自己的密钥,所以需要这个回调,要求app回传login刚刚所提供的字符的加密后的内容进行比对
 	@At("/user/login/app/callback")
 	public Object appLoginCallback(@Param("token") String token,
 			HttpSession session) {
@@ -96,6 +102,7 @@ public Object appLoginCallback(@Param("token") String token,
 		return Ajax.fail();
 	}
 
+	//创建app,并生成密钥
 	@At("/app/create/?")
 	@Filters({@By(type=ActionFilter.class, args={"ioc:authFilter"})})
 	@Auth("app.create")
@@ -119,6 +126,7 @@ public void invoke(DB arg0) {
 		return Ajax.ok().setData(dao.findOne(App.class, new BasicDBObject("name", name)));
 	}
 
+	//新创建的app是未激活状态,这个方法会激活app
 	@At("/app/active/?")
 	@Filters({@By(type=ActionFilter.class, args={"ioc:authFilter"})})
 	@Auth("app.active")
@@ -129,6 +137,7 @@ public Object activeApp(String name) {
 		return Ajax.ok();
 	}
 
+	//停用app,使其回到未激活状态
 	@At("/app/deactive/?")
 	@Filters({@By(type=ActionFilter.class, args={"ioc:authFilter"})})
 	@Auth("app.deactive")

src/org/nutz/ngqa/module/CoreModule.java

@@ -35,14 +35,14 @@
 import com.mongodb.DBCollection;
 import com.mongodb.DBRef;
 
-@IocBean(create="init")
+@IocBean(create="init") //创建本对象时,执行init方法
 @InjectName
 @Filters({@By(type=AjaxCheckSession.class,args={"me"})})
 public class CoreModule {
 
 	/*question的title是必须的,其他都是可选*/
 	@At("/ask")
-	@AdaptBy(type=JsonAdaptor.class)
+	@AdaptBy(type=JsonAdaptor.class) //将输入流以Json格式读取,生成参数表
 	public AjaxReturn createQuestion(final @Param("..")Question question, @Attr("me") User user) {
 		if (question == null || Lang.length(question.getTitle()) < 5 || Lang.length(question.getTitle()) > 100)
 			return Ajax.fail().setMsg("Not OK");
@@ -51,7 +51,7 @@ public AjaxReturn createQuestion(final @Param("..")Question question, @Attr("me"
 		question.setUpdatedAt(new Date());
 		question.setTags(new String[0]);
 		question.setAnswers(new Answer[0]);
-		dao.runNoError(new Callback<DB>() {
+		dao.runNoError(new Callback<DB>() { //以安全方式执行,其实就是执行完毕后,执行getError来确保顺利完成
 			public void invoke(DB arg0) {
 				dao.save(question);
 			}
@@ -60,8 +60,8 @@ public void invoke(DB arg0) {
 	}
 
 	/*获取具体的question*/
-	@At("/question/?")
-	@Filters()
+	@At("/question/?") //最后面一个问号,代表一个路径参数,将设置为questionId的值
+	@Filters() //查询无需任何权限
 	@Ok("smart:/question/one")
 	public Object fetch(String questionId) {
 		Question question = dao.findById(Question.class, questionId);
@@ -70,14 +70,15 @@ public Object fetch(String questionId) {
 		return question;
 	}
 
+	/**通用查询入口,复杂查询都走这个入口*/
 	@At("/question/query")
-	public Object query(QuestionQuery query) {
+	public Object query(@Param("..")QuestionQuery query) { //@Param("..")的意思是,参数abc对应这个类的abc属性,从而构建一个完整的对象
 		return questionMS.query(query);
 	}
 
-	@At("/question/?/answer/add")
+	@At("/question/?/answer/add") //问号放在中间也是可以的,数量不限
 	@AdaptBy(type=JsonAdaptor.class)
-	public AjaxReturn addAnswer(final String questionId, final @Param("..")Answer answer, @Attr("me")User user) {
+	public AjaxReturn addAnswer(final String questionId, final @Param("..")Answer answer, @Attr("me")User user) { //@Attr的意思是取req.getAttr或者session.getAttr
 		if (answer == null || Lang.length(answer.getContent()) < 5)
 			return Ajax.fail().setMsg("Not OK");
 		Question question = dao.findById(Question.class, questionId);
@@ -99,8 +100,9 @@ public void invoke(DB db) {
 		return Ajax.ok();
 	}
 
-	@At("/question/?/tag/add/?")
-	public AjaxReturn addTag(String questionId,String tag, @Attr("me")User user) {
+	/**为一个问题设置一个标签*/
+	@At("/question/?/tag/add/?") //多个问好的情况,很方便,对吧?
+	public AjaxReturn addTag(String questionId,String tag, @Attr("me")User user) { 
 		if (tag == null || Strings.isBlank(tag) || tag.trim().length() < 3 || tag.trim().length() > 12)
 			return Ajax.fail().setMsg("Not OK");
 		tag = tag.trim().intern();
@@ -111,6 +113,7 @@ public AjaxReturn addTag(String questionId,String tag, @Attr("me")User user) {
 		return Ajax.ok();
 	}
 
+	/**为一个问题移除一个标签*/
 	@At("/question/?/tag/remove/?")
 	public AjaxReturn removeTag(String questionId,String tag, @Attr("me")User user) {
 		BasicDBObject update = new BasicDBObject();
@@ -120,16 +123,19 @@ public AjaxReturn removeTag(String questionId,String tag, @Attr("me")User user)
 		return Ajax.ok();
 	}
 
+	/**监视一个问题,问题被修改的时候(添加删除答案等),发出提醒*/
 	@At("/question/?/watch")
 	public void watch(String questionId, @Attr("me") User me) {
 		dao.update(Question.class, new BasicDBObject("_id", new ObjectId(questionId)), new BasicDBObject("$addToSet", new BasicDBObject("watchers", new DBRef(null, "user", new ObjectId(me.getId())))));
 	}
 
+	/**不再监视一个问题*/
 	@At("/question/?/unwatch")
 	public void unwatch(String questionId, @Attr("me") User me) {
 		dao.update(Question.class, new BasicDBObject("_id", new ObjectId(questionId)), new BasicDBObject("$pop", new BasicDBObject("watchers", new DBRef(null, "user", new ObjectId(me.getId())))));
 	}
 
+	/**更新问题的某些属性*/
 	@At("/question/?/update")
 	public Object update(String questionId, @Param("..")Question question, @Attr("me")User me) {
 		Question q = dao.findById(Question.class, questionId);

src/org/nutz/ngqa/module/UserModule.java

@@ -60,7 +60,7 @@ public void login(String provider, HttpSession session, HttpServletRequest req)
 			}
 			returnTo = sb.toString();
 		}
-		SocialAuthManager manager = new SocialAuthManager();
+		SocialAuthManager manager = new SocialAuthManager(); //每次都要新建哦
 		manager.setSocialAuthConfig(config);
 		session.setAttribute("openid.manager", manager);
 		String url = manager.getAuthenticationUrl(provider, returnTo);
@@ -72,7 +72,7 @@ public void login(String provider, HttpSession session, HttpServletRequest req)
 	@At("/logout")
 	@Ok("void")
 	public void logout(HttpSession session) {
-		session.invalidate();
+		session.invalidate(); //销毁会话,啥都米有了
 	}
 
 	/*无需做链接,这是OpenID的回调地址*/
@@ -114,9 +114,9 @@ public void invoke(DB arg0) {
 
 	public void init() throws Exception {
 		SocialAuthConfig config = new SocialAuthConfig();
-		File devConfig = Files.findFile("oauth_consumer.properties_dev");
+		File devConfig = Files.findFile("oauth_consumer.properties_dev"); //开发期所使用的配置文件
 		if (devConfig == null)
-			devConfig = Files.findFile("oauth_consumer.properties");
+			devConfig = Files.findFile("oauth_consumer.properties"); //真实环境所使用的配置文件
 		if (devConfig == null)
 			config.load(new NullInputStream());
 		else

src/org/nutz/ngqa/mvc/AtomView.java

@@ -5,14 +5,13 @@
 
 import org.nutz.mvc.View;
 
-import com.colorfulsoftware.atom.FeedDoc;
-
+/**生成Atom1.0格式的全文输出*/
 public class AtomView implements View {
 
 	@Override
 	public void render(HttpServletRequest req, HttpServletResponse resp,
 			Object obj) throws Throwable {
-		FeedDoc doc = new FeedDoc();
+//		FeedDoc doc = new FeedDoc();
 
 	}